Πώς να ρυθμίσετε το Sphinx για να τεκμηριώσετε τον κώδικα Python σας

Το Sphinx είναι ένα από τα πιο δημοφιλή εργαλεία για τη δημιουργία τεκμηρίωσης. Σε όλη την κοινότητα της Python, οι προγραμματιστές χρησιμοποιούν αυτό το δωρεάν λογισμικό ανοιχτού κώδικα. Μπορεί να εξαγάγει κείμενο απευθείας από τον κώδικα ή τα αρχεία σήμανσης και στη συνέχεια να το χρησιμοποιήσει για τη δημιουργία τεκμηρίωσης σε διάφορες μορφές, όπως απλό κείμενο, HTML, PDF και EPUB.

Ρύθμιση της Σφίγγας

Πριν ρυθμίσετε το Sphinx, ρίξτε μια ματιά σε αυτό που κάνει και μερικά από τα κύρια χαρακτηριστικά του.

Τι είναι η Σφίγγα και τι κάνει;

Όπως αναφέρθηκε, το Sphinx είναι μια γεννήτρια τεκμηρίωσης. Από προεπιλογή, χρησιμοποιεί τη γλώσσα σήμανσης reStructuredText (RST), αλλά μέσω επεκτάσεων τρίτων, μπορεί επίσης χρησιμοποιήστε τη Markdown, τη δημοφιλή γλώσσα σήμανσης απλού κειμένου. Στη συνέχεια, μετατρέπει αυτά τα αρχεία RST ή markdown σε HTML, PDF, μη αυτόματες σελίδες ή άλλες μορφές που προτιμάτε.

Μερικά από τα χαρακτηριστικά που περιλαμβάνει η Sphinx είναι:

• Δυνατότητα δημιουργίας τεκμηρίωσης από κώδικα.
• Δυνατότητα διασταύρωσης διαφορετικών σελίδων εγγράφων χρησιμοποιώντας αυτόματους συνδέσμους για συναρτήσεις, τάξεις, αναφορές και όρους γλωσσαρίου.
• Επισήμανση σύνταξης για μπλοκ κώδικα.
• Υποστήριξη για θέματα που μπορούν να αλλάξουν την εμφάνιση και την αίσθηση των εγγράφων.
• Εύκολος ορισμός του δέντρου εγγράφων μέσω ενός πίνακα περιεχομένων.
• Δυνατότητα ενσωμάτωσης με επεκτάσεις τρίτων για προσθήκη περισσότερων λειτουργιών στα έγγραφα, όπως δοκιμή αποσπασμάτων κώδικα.

Εγκατάσταση Sphinx

Πριν εγκαταστήσετε το Sphinx, βεβαιωθείτε ότι έχετε Η Python 3 είναι εγκατεστημένη στο περιβάλλον ανάπτυξης σας. Στη συνέχεια, μπορείτε να χρησιμοποιήσετε τον διαχειριστή πακέτων pip για να εγκαταστήσετε το Sphinx εκτελώντας την ακόλουθη εντολή στο τερματικό σας:

pip εγκατάσταση σφίγγα

Αυτό θα κατεβάσει και θα εγκαταστήσει το Sphinx και τις εξαρτήσεις του.

Μετά την εγκατάσταση, εκτελέστε τα παρακάτω στη γραμμή εντολών.

Sphinx-build --έκδοση

Εάν όλα λειτουργούσαν καλά, θα πρέπει να δείτε τον αριθμό έκδοσης για το πακέτο Sphinx που μόλις εγκαταστήσατε.

Δημιουργία ενός νέου έργου Sphinx

Αφού εγκαταστήσετε το Sphinx, μεταβείτε στον κατάλογο εργασίας σας και εκτελέστε την εντολή sphinx-quickstart για να δημιουργήσετε ένα νέο έργο Sphinx.

σφίγγα-γρήγορη εκκίνηση

Αυτή η εντολή θα σας ζητήσει να απαντήσετε σε μια σειρά ερωτήσεων σχετικά με τον τρόπο διαμόρφωσης του έργου Sphinx. Μπορείτε να καθορίσετε το όνομα του έργου και να χρησιμοποιήσετε τις προεπιλεγμένες επιλογές για τις άλλες ερωτήσεις. Στο μέλλον, μπορεί να θέλετε να προσαρμόσετε τις απαντήσεις με βάση το έργο σας.

Εάν παραθέσετε τα περιεχόμενα του καταλόγου σας, θα δείτε ότι αυτή η εντολή δημιουργεί ορισμένα αρχεία για εσάς. Το conf.py περιέχει τις τιμές διαμόρφωσης και το index.rst χρησιμεύει ως η σελίδα υποδοχής της τεκμηρίωσής σας. Ο κατάλογος κατασκευής θα φιλοξενήσει την τεκμηρίωση που δημιουργήθηκε και το Sphinx χρησιμοποιεί ένα Makefile (make.bat στα Windows) για τη δημιουργία της τεκμηρίωσης.

Γραπτή τεκμηρίωση με χρήση της Σφίγγας

Το αρχείο index.rst στη ρίζα του καταλόγου σας είναι η αρχική σελίδα της εφαρμογής σας. Επομένως, ανοίξτε το με ένα πρόγραμμα επεξεργασίας κειμένου όπως το VS Code—ή οποιοδήποτε άλλο καλό, δωρεάν πρόγραμμα επεξεργασίας κώδικα— για να το επεξεργαστείτε.

Μπορείτε να αλλάξετε το index.rst όπως νομίζετε, αλλά ένα πράγμα που θα έπρεπε τουλάχιστον να έχει είναι η οδηγία root toctree (δέντρο πίνακα περιεχομένων). Αυτό είναι απαραίτητο καθώς συνδέει πολλαπλά αρχεία σε μια ενιαία ιεραρχία εγγράφων.

Για να προσθέσετε τεκμηρίωση στο αρχείο index.rst, μπορείτε να χρησιμοποιήσετε τη σήμανση RST.

Για παράδειγμα, εξετάστε ένα αρχείο index.rst για τη λειτουργική μονάδα math_utils. Αυτό το αρχείο μπορεί να περιλαμβάνει μια σύντομη επισκόπηση του σκοπού της ενότητας και έναν πίνακα περιεχομένων που συνδέεται με άλλες σελίδες της τεκμηρίωσης.

Καλώς ήρθατε στο Math Utils
.. toctree::
 :maxdepth: 2
Ξεκινώντας

Για να χρησιμοποιήσετε αυτήν την ενότητα, θα χρειαστείτε τα εξής:
* Εγκαταστάθηκε η Python.
* Ένα πρόγραμμα επεξεργασίας κειμένου
Math Utils

Η ενότητα "math-utils" παρέχει βασικές μαθηματικές συναρτήσεις όπως πρόσθεση και
αφαίρεση.

Μπορείτε να προσθέσετε περισσότερα αρχεία .rst όπως απαιτείται. Για παράδειγμα, μπορείτε να δημιουργήσετε έναν οδηγό συνεισφοράς σε ένα αρχείο με το όνομα contributing.rst που περιέχει τις ακόλουθες οδηγίες συνεισφοράς.

Οδηγός συνεισφοράς
Χαιρετίζουμε τις συνεισφορές στο έργο μας! Ακολουθούν ορισμένες οδηγίες για
συμβάλλοντας:
- Διαχωρίστε το έργο στο GitHub.
- Κάντε τις αλλαγές σας σε νέο υποκατάστημα.
- Γράψτε δοκιμές για να βεβαιωθείτε ότι οι αλλαγές σας λειτουργούν σωστά.
- Υποβάλετε ένα αίτημα έλξης με τις αλλαγές σας.
- Πραγματοποιήστε τυχόν αλλαγές που ζητούνται.
Σας ευχαριστούμε που συνεισφέρετε!

Στη συνέχεια, μπορείτε να συνδέσετε αυτό το αρχείο από το index.rst προσθέτοντας μια νέα ενότητα στην οδηγία toctree:

.. toctree::
 :maxdepth: 2
 :caption: Πίνακας περιεχομένων

 συμβάλλοντας

Αυτό δημιουργεί ένα νέο στοιχείο που ονομάζεται συνεισφορά στον πίνακα περιεχομένων που μεταφέρει τον χρήστη στη σελίδα συνεισφοράς όταν κάνει κλικ.

Μόλις γράψετε την τεκμηρίωση, το επόμενο βήμα είναι να την δημιουργήσετε. Εδώ, η δημιουργία της τεκμηρίωσης σημαίνει τη δημιουργία σελίδων HTML, εγχειριδίων ή PDF από τα αρχεία RST.

Κατασκευή της Τεκμηρίωσης

Για να δημιουργήσετε την τεκμηρίωση χρησιμοποιώντας το Sphinx, θα χρειαστεί να εκτελέσετε την εντολή make html στη ρίζα του φακέλου σας όπου βρίσκεται το makefile.

φτιάξτε html

Θα πρέπει να δείτε τα αρχεία HTML στο φάκελο build. Εάν υπήρξαν σφάλματα κατά τη διάρκεια της κατασκευής, η Sphinx θα σας ενημερώσει στο τερματικό.

Για να προβάλετε την τεκμηρίωση, ανοίξτε το αρχείο index.html στο πρόγραμμα περιήγησής σας:

Θα πρέπει να μπορείτε να πλοηγηθείτε στον συνεισφέροντα οδηγό από τον πίνακα περιεχομένων.

Προσαρμογή της Τεκμηρίωσης

Αυτήν τη στιγμή, η τεκμηρίωση έχει κάποιο βασικό στυλ. Εάν θέλετε να το προσαρμόσετε, προσθέτοντας ίσως τα χρώματα της επωνυμίας σας ή ακόμη και προσθέτοντας μια σκοτεινή λειτουργία, μπορείτε να εγκαταστήσετε και να χρησιμοποιήσετε άλλα ενσωματωμένα θέματα ή δημιουργήστε το δικό σας προσαρμοσμένο θέμα.

Για να το δείξετε, δοκιμάστε να αλλάξετε το θέμα σε αυτό που ονομάζεται φύση:

1. Ανοίξτε το αρχείο διαμόρφωσης Sphinx conf.py στον κατάλογο του έργου Sphinx.
2. Αναζητήστε τη γραμμή που ορίζει την επιλογή html_theme και αλλάξτε την σε φύση
3. Αποθηκεύστε το αρχείο διαμόρφωσης και δημιουργήστε ξανά την τεκμηρίωση για να δείτε τις αλλαγές σας.

Αυτή είναι η αρχική σελίδα της τεκμηρίωσης.

Εάν δεν θέλετε να χρησιμοποιήσετε τα ενσωματωμένα θέματα, μπορείτε πάντα να χρησιμοποιήσετε ένα θέμα τρίτων Sphinx αντι αυτου.

Τεκμηρίωση του κώδικά σας με χρήση εγγράφων

Το Sphinx δημιουργεί την τεκμηρίωση Python από κείμενο που γράφετε σε αρχεία RST. Αν και αυτό είναι αρκετό σε ορισμένες περιπτώσεις, μπορεί επίσης να θέλετε να χρησιμοποιήσετε συμβολοσειρές εγγράφων στον κώδικά σας σε αυτό σε επίπεδο λειτουργικής μονάδας.

Οι συμβολοσειρές εγγράφων ζουν απευθείας μέσα στα αρχεία πηγής του έργου σας. Σας επιτρέπουν να περιγράψετε τι κάνει ο κώδικας, να παρέχετε παραδείγματα και ακόμη και να δημιουργήσετε δοκιμές για αυτά τα παραδείγματα. Αφού γράψετε συμβολοσειρές εγγράφων, μπορείτε να δημιουργήσετε τεκμηρίωση από αυτές χρησιμοποιώντας το Sphinx.