Τι να διαβάσετε μετά

Έχετε, λοιπόν, διαβάσει όλο το εισαγωγικό κομμάτι (Ξεκινώντας) και αποφασίσατε ότι θέλετε να χρησιμοποιήσετε το Django. Το μόνο που κάναμε στην εισαγωγή ήταν να ξύσουμε την επιφάνεια (στην πραγματικότητα, αν διαβάσατε κάθε λέξη, έχετε καλύψει μόλις το 5% του συνόλου του εγχειριδίου του Django).

Επόμενα βήματα;

Ανέκαθεν ήμασταν φαν της λογικής ‘μαθαίνω μέσα από πράξεις’. Μέχρι αυτό το σημείο γνωρίζετε αρκετά για να ξεκινήσετε ένα project μόνοι σας και να παίξετε λίγο μαζί του. Όταν θελήσετε να μάθετε νέες τεχνικές-κόλπα δεν έχετε παρά να επισκεφτείτε το documentation του Django.

Έχουμε προσπαθήσει πάρα πολύ ούτως ώστε να κάνουμε το documentation του Django όσο γίνεται πιο χρήσιμο, πλήρες και εύκολο στην ανάγνωση. Στη συνέχεια του παρόντος άρθρου θα ασχοληθούμε με το πως λειτουργεί το documentation προκειμένου να μπορείτε να επωφεληθείτε τα μέγιστα από αυτό.

(Ναι! Αυτό είναι ένα documentation για το documentation. Μείνετε ήσυχοι όμως, δεν σκοπεύουμε να αφιερώσουμε ολόκληρο άρθρο στο πως να διαβάσετε ένα documentation.)

Βρίσκοντας κάτι μέσα στο εγχειρίδιο

Το Django έχει πλούσιο εγχειρίδιο – περίπου 450,000 λέξεις που συνεχίζουν να αυξάνονται – οπότε το να βρει κανείς αυτό που αναζητά μπορεί να αποδειχθεί δύσκολο. Μερικά σημεία για να ξεκινήσετε είναι η σελίδα Σελίδα αναζήτησης και η σελίδα Ευρετήριο.

Ή, απλά, μπορείτε να περιηγηθείτε σε ολόκληρο το site!

Πως είναι οργανωμένο το documentation

Το βασικό documentation του Django είναι χωρισμένο σε «chunks» (κομμάτια) τα οποία έχουν σχεδιαστεί να εξυπηρετούν διαφορετικούς σκοπούς:

• Το άρθρο Ξεκινώντας είναι σχεδιασμένο για αυτούς που δεν είναι μυημένοι στο Django – ή στο Web development γενικότερα. Δεν καλύπτει κάτι εις βάθος, αλλά δίνει μια εικόνα του developing χρησιμοποιώντας το Django.

• Από την άλλη, το άρθρο Χρησιμοποιώντας το Django, βουτάει βαθιά στις επιμέρους οντότητες του Django. Υπάρχουν πλήρης οδηγοί (guides) στα σύστημα μοντέλων, template engine, framework για φόρμες και πολλά άλλα.

  Τον περισσότερο χρόνο σας θα τον περάσετε διαβάζοντας και ξαναδιαβάζοντας τους παραπάνω οδηγούς. Όταν τους κατανοήσετε τότε θα ξέρετε (σχεδόν τα πάντα για) το πως λειτουργεί το Django.

• Το Web development είναι συχνά αχανές και όχι βαθύ – τα προβλήματα που προκύπτουν αφορούν διάφορους τομείς. Έχουμε γράψει ένα σετ από οδηγούς how-to οι οποίοι απαντούν κοινές ερωτήσεις του τύπου «Πως να …?». Εδώ θα βρείτε πληροφορίες σχετικά με τη δημιουργία PDFs με το Django, σύνταξη δικών σας template tags και πολλά άλλα.

  Απαντήσεις σε πραγματικά συχνές ερωτήσεις μπορείτε να βρείτε (που αλλού) στις Συχνές ερωτήσεις (FAQ).

• Οι οδηγοί και τα how-to δεν καλύπτουν κάθε κλάση, συνάρτηση και μέθοδο διαθέσιμη στο Django – αυτό μπορεί να γίνει εκνευριστικό όταν προσπαθείτε να μάθετε κάτι καινούργιο. Αντιθέτως, οι λεπτομέρειες σχετικά με κλάσεις, συναρτήσεις, μεθόδους και modules κρατούνται στο άρθρο αναφορά. Εκεί θα βρείτε το οτιδήποτε αφορά μια συγκεκριμένη συνάρτηση ή οτιδήποτε άλλο σχετικό.

• Αν ενδιαφέρεστε να κάνετε deploy ένα project για δημόσια χρήση (με άλλα λόγια να ανεβάσετε το project σας σε κάποιον πραγματικό server), παρέχουμε αρκετούς οδηγούς για διάφορα deployment περιβάλλοντα, όπως επίσης και μια deployment checklist για μερικά πράγματα που πρέπει να λάβετε υπόψιν σας προτού “ανεβάσετε” το project σας.

• Τέλος, υπάρχει ένα «ειδικό» τμήμα του εγχειριδίου το οποίο δεν είναι και πολύ σχετικό με τους περισσότερους developers. Αυτό περιλαμβάνει τα άρθρα σημειώσεις έκδοσης (release notes) και internals documentation για αυτούς που θέλουν να προσθέσουν κώδικα στο Django και κάποια άλλα άρθρα σχετικά με πράγματα που δεν μπορούσαν να μπουν πουθενά αλλού.

Πως ανανεώνετε το documentation

Όπως ακριβώς ο πηγαίος κώδικας του Django αναπτύσσεται και βελτιώνεται καθημερινώς, έτσι και το documentation μας συνεχώς βελτιώνεται. Βελτιώνουμε το documentation για πολλούς λόγους:

• Διορθώνουμε το περιεχόμενο, όπως γραμματικά/τυπογραφικά λάθη.
• Προσθέτουμε πληροφορίες και/ή παραδείγματα σε κάποια κομμάτια τα οποία χρειάζονται επέκταση.
• Συμπεριλαμβάνουμε στο εγχειρίδιο τα Django features τα οποία λείπουν. (Η λίστα αυτών των features μειώνεται αλλά δεν παύει να υπάρχει.)
• Εμπλουτίζουμε το εγχειρίδιο για να συμπεριληφθούν τα νέα features που προστίθενται ή όταν αλλάζουν τα Django APIs ή κάποιες συμπεριφορές.

Το documentation του Django φυλάσσεται στο ίδιο source control system όπως και ο πηγαίος κώδικας. Βρίσκεται στο φάκελο docs του Git repository. Κάθε άρθρο στην ιστοσελίδα μας είναι ένα ξεχωριστό αρχείο κειμένου στο repository.

Που να το βρείτε

Μπορείτε να διαβάσετε το Django documentation με αρκετούς τρόπους. Με σειρά προτίμησης, είναι οι εξής:

Στο Web

The most recent version of the Django documentation lives at https://docs.djangoproject.com/en/dev/. These HTML pages are generated automatically from the text files in source control. That means they reflect the «latest and greatest» in Django – they include the very latest corrections and additions, and they discuss the latest Django features, which may only be available to users of the Django development version. (See Διαφορές μεταξύ εκδόσεων below.)

Παρακαλούμε αν έχετε τυχόν αλλαγές, διορθώσεις ή προτάσεις που αφορούν το documentation να τις καταθέσετε στο ticket system προκειμένου να συμβάλλετε στην βελτίωση του. Οι Django developers παρακολουθούν το ticket system και χρησιμοποιούν το δικό σας feedback για να βελτιώσουν το documentation προς όφελος όλων.

Ωστόσο, σημειώστε, ότι τα tickets θα πρέπει να συσχετίζονται με το documentation και όχι με κάποια τεχνική υποστήριξη. Αν χρειάζεστε βοήθεια με τη δική σας Django εγκατάσταση, δοκιμάστε τη mailing list των django-users ή το κανάλι #django IRC channel.

Σε απλό κείμενο

Για ανάγνωση χωρίς να είστε συνδεδεμένοι στο internet ή απλά για δική σας διευκόλυνση, μπορείτε να διαβάσετε το documentation του Django σε απλό κείμενο.

If you’re using an official release of Django, the zipped package (tarball) of the code includes a docs/ directory, which contains all the documentation for that release.

If you’re using the development version of Django (aka the master branch), the docs/ directory contains all of the documentation. You can update your Git checkout to get the latest changes.

Ένας low-level τρόπος να επωφεληθείτε από το documentation σε μορφή κειμένου είναι χρησιμοποιώντας την εντολή του Unix grep. Η εντολή αυτή σας επιτρέπει να ψάξετε κάποια φράση σε ολόκληρο το documentation. Για παράδειγμα, η παρακάτω εντολή θα ψάξει σε κάθε άρθρο του documentation και θα σας δείξει όλες τις αναφορές σχετικά με τη λέξη «max_length»:

Linux/macOS

$ grep -r max_length /path/to/django/docs/

Windows

...\> grep -r max_length \path\to\django\docs\

Στην HTML, τοπικά

Μπορείτε να έχετε ένα τοπικό αντίγραφο του HTML documentation ακολουθώντας τα παρακάτω βήματα:

• Το documentation του Django χρησιμοποιεί ένα σύστημα που ονομάζεται Sphinx προκειμένου να μετατρέψει το απλό κείμενο σε HTML. Θα χρειαστεί να εγκαταστήσετε το Sphinx είτε κατεβάζοντας το απ’ την επίσημη ιστοσελίδα και έπειτα εγκαθιστώντας το ή χρησιμοποιώντας το pip:

  Linux/macOS

  $ pip install Sphinx
  

  Windows

  ...\> pip install Sphinx
  

• Έπειτα, χρησιμοποιήστε το συμπεριλαμβανόμενο αρχείο Makefile για να μετατρέψετε το documentation σε HTML:

  $ cd path/to/django/docs
  $ make html
  

  Θα χρειαστεί να έχετε εγκατεστημένο το GNU Make για να δουλέψει.

  Αν χρησιμοποιείτε Windows μπορείτε, εναλλακτικά, να χρησιμοποιήσετε το συμπεριλαμβανόμενο batch αρχείο:

  cd path\to\django\docs
  make.bat html
  

• Η όλη διαδικασία με το Sphinx θα δουλέψει για εκδόσεις μεγαλύτερες ή ίσης της 0.6, αλλά προτείνουμε να χρησιμοποιήσετε το Sphinx 1.0.2 ή νεώτερο.

Διαφορές μεταξύ εκδόσεων

The text documentation in the master branch of the Git repository contains the «latest and greatest» changes and additions. These changes include documentation of new features targeted for Django’s next feature release. For that reason, it’s worth pointing out our policy to highlight recent changes and additions to Django.

Ακολουθούμε την παρακάτω πολιτική:

• The development documentation at https://docs.djangoproject.com/en/dev/ is from the master branch. These docs correspond to the latest feature release, plus whatever features have been added/changed in the framework since then.
• As we add features to Django’s development version, we update the documentation in the same Git commit transaction.
• To distinguish feature changes/additions in the docs, we use the phrase: «New in Django Development version» for the version of Django that hasn’t been released yet, or «New in version X.Y» for released versions.
• Documentation fixes and improvements may be backported to the last release branch, at the discretion of the committer, however, once a version of Django is no longer supported, that version of the docs won’t get any further updates.
• The main documentation Web page includes links to documentation for previous versions. Be sure you are using the version of the docs corresponding to the version of Django you are using!