Χρησιμοποιήστε το Sphinx για να δημιουργήσετε τεκμηρίωση σε πολλαπλές μορφές στο CentOS 7

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

Σε αυτό το σεμινάριο, θα καλύψουμε τη διαδικασία εγκατάστασης και χρήσης Sphinxσε μια παρουσία CentOS 7 x64 στην πλατφόρμα του Vult.

Προαπαιτούμενα

• Μια παρουσία CentOS 7 x64.
• Ένας χρήστης sudo .

Βήμα 1: Ενημερώστε το σύστημα

sudo yum update
sudo shutdown -r now

Βήμα 2: Εγκαταστήστε το pip and Sphinx

sudo yum install -y python-devel python-setuptools python-pip
sudo pip install --upgrade pip
sudo pip install -U Sphinx

Βήμα 3: Ρυθμίστε τη βασική διαμόρφωση για την τεκμηρίωσή σας

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

sphinx-quickstart είναι παρόμοιο με έναν οδηγό εγκατάστασης που θα σας ζητήσει ερωτήσεις που καθορίζουν τις πτυχές του έργου σας.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Βήμα 4: Κατασκευάστε την ιεραρχία για την τεκμηρίωσή σας

Από προεπιλογή, ο sphinx-quickstartοδηγός θα δημιουργήσει πολλούς καταλόγους και αρχεία.

_build           # The directory for containing Sphinx output
conf.py          # The file containing your project configurations
index.rst        # The master file containing the hierarchy of your documentation
make.bat         # A Windows command file
Makefile         # A file necessary for running the make command
_static          # The directory for static files, including custom stylesheets, pictures, etc.
_templates       # The directory for custom templates

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

Ανοίξτε το με ένα πρόγραμμα επεξεργασίας κειμένου:

vi index.rst

Καθώς εξετάζετε το αρχείο, θα παρατηρήσετε μια ενότητα που ονομάζεται toctree. Εάν έχετε άλλα αρχεία πηγής ( *.rst) για την τεκμηρίωσή σας, θα πρέπει να τα προσδιορίσετε στην toctreeενότητα: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Είναι επιτακτική ανάγκη να:

• Αφήστε μια κενή σειρά πάνω από την καταχώρισή σας.
• Μην προσθέτετε επίθημα στα αρχεία προέλευσης με .rst.
• Τοποθετήστε τα αρχεία προέλευσης με την αντίστοιχη σειρά τους.
• Χρησιμοποιήστε μόνο ένα όνομα αρχείου ανά σειρά.
• Κάντε εσοχή στα ονόματα των αρχείων σας με :maxdepth: 2.

Αφού ολοκληρώσετε τις τροποποιήσεις σας, αποθηκεύστε το αρχείο σας και βγείτε από το πρόγραμμα επεξεργασίας κειμένου.

ESC
:!wq

Βήμα 5: Δημιουργήστε αρχεία προέλευσης που καθορίζονται παραπάνω

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

Όλα τα αρχεία προέλευσης πρέπει να είναι συμβατά με το reStructuredText markup language. Για περισσότερες πληροφορίες, ανατρέξτε στο reStructuredText Primer .

Βήμα 6: Εξαγωγή της έκδοσης HTML της τεκμηρίωσής σας

Μόλις ολοκληρώσετε τη σύνταξη της τεκμηρίωσής σας, μπορείτε να εξάγετε την εργασία σας HTML format εκτελώντας την παρακάτω εντολή:

make html

Η έξοδος θα αποθηκευτεί στον κατάλογο ./\_build/htmlπου περιλαμβάνει όλα τα απαραίτητα για την προβολή του αρχείου σε μια περιήγηση στο web.

Αυτό ολοκληρώνει το σεμινάριο μας.