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

Έχετε, λοιπόν, διαβάσει όλο το εισαγωγικό κομμάτι (Ξεκινώντας) και αποφασίσατε ότι θέλετε να χρησιμοποιήσετε το 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

Η πιο πρόσφατη έκδοση του documentation του Django υπάρχει στη διεύθυνση https://docs.djangoproject.com/en/dev/. Αυτές οι HTML σελίδες παράγονται αυτόματα από τα αρχεία κειμένου στο source control (git). Αυτό σημαίνει ότι περιλαμβάνουν τα «τελευταία και τα καλύτερα» του Django – δηλαδή, τις τελευταίες διορθώσεις και προσθήκες. Επίσης συζητούν τα τελευταία Django features, τα οποία είναι διαθέσιμα μόνο για τους χρήστες που χρησιμοποιούν την αναπτυξιακή έκδοση του Django (development version). (Δείτε στις «Διαφορές μεταξύ εκδόσεων» παρακάτω.)

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

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

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

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

Αν χρησιμοποιείτε μια επίσημη έκδοση του Django, σημειώστε ότι το συμπιεσμένο πακέτο (tarball) του πηγαίου κώδικα περιλαμβάνει το φάκελο docs/, ο οποίος περιλαμβάνει το documentation του Django για αυτή την έκδοση.

Αν χρησιμοποιείται την αναπτυξιακή έκδοση του Django (γνωστή και ως «trunk»), σημειώστε ότι ο φάκελος docs/ περιλαμβάνει όλο το documentation. Μπορείτε να κάνετε update το Git checkout προκειμένου να λάβετε τις τελευταίες αλλαγές.

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

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

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

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

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

  $ 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 ή νεώτερο.

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

Όπως προαναφέρθηκε, το documentation του Django σε μορφή κειμένου μέσα στο Git repository περιέχει τις «τελευταίες και καλύτερες» αλλαγές και προσθήκες. Αυτές οι αλλαγές συχνά συμπεριλαμβάνονται στο εγχειρίδιο με τα νέα features που προστέθηκαν στην αναπτυξιακή έκδοση του Django – την Git («trunk») έκδοση, δηλαδή, του Django. Γι’ αυτό το λόγο, αξίζει να σημειωθεί η πολιτική μας στη διατήρηση του documentation για τις διάφορες εκδόσεις του framework.

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

• Το πρωτεύον documentation στο djangoproject.com είναι μια HTML έκδοση των νεώτερων docs στο Git. Αυτά τα docs αντικατοπτρίζουν, πάντα, την τελευταία επίσημη έκδοση της κυκλοφορίας του Django, μαζί με οποιαδήποτε features έχουμε προσθέσει/αλλάξει στο framework από την τελευταία κυκλοφορία.
• Καθώς προσθέτουμε νέα features στην αναπτυξιακή έκδοση του Django (development version), προσπαθούμε να ανανεώσουμε το documentation στο ίδιο Git commit transaction.
• Για να διαχωρίσουμε τις αλλαγές/προσθήκες των features μέσα στα docs, χρησιμοποιούμε εκφράσεις όπως: «Νέο στην έκδοση X.Y», όπου X.Y η επόμενη έκδοση (δηλαδή, αυτή η οποία γίνεται developed).
• 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.
• Η κύρια ιστοσελίδα του documentation περιλαμβάνει links για το documentation πολλών προηγούμενων εκδόσεων. Σιγουρευτείτε ότι χρησιμοποιείτε την έκδοση των docs η οποία αντιστοιχεί με την έκδοση του Django που χρησιμοποιειτε!