Bruk Sphinx til å lage dokumentasjon i flere formater på CentOS 7

Sphinx er et nyttig Python-basert verktøy for teknikere og forfattere som lar dem enkelt lage elegant, fullt funksjonell dokumentasjon i ulike formater. Med Sphinx skriver du dokumenter ved å bruke reStructuredText – et lett markeringsspråk – for det første, så kan du få utdataene i flere formater, inkludert HTML, LaTeX, PDF, ePub og andre.

I denne opplæringen vil vi dekke prosessen med å installere og bruke Sphinxpå en CentOS 7 x64-forekomst på Vults plattform.

Forutsetninger

• En CentOS 7 x64-forekomst.
• En sudo-bruker .

Trinn 1: Oppdater systemet

sudo yum update
sudo shutdown -r now

Trinn 2: Installer pip og Sphinx

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

Trinn 3: Konfigurer den grunnleggende konfigurasjonen for dokumentasjonen

Før du begynner å bruke Sphinx, må du spesifisere kildekatalogen som Sphinxskal kjøre og lagre all dokumentasjonen. Når du har opprettet katalogen du har tenkt å bruke, kan du kjøre sphinx-quickstartsom vil initialisere Sphinxog opprette den nødvendige grunnleggende konfigurasjonen.

sphinx-quickstart ligner på en oppsettsveiviser som vil stille deg spørsmål som bestemmer aspektene ved prosjektet ditt.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Trinn 4: Konstruer hierarkiet for dokumentasjonen

Som standard vil sphinx-quickstartveiviseren opprette flere kataloger og filer.

_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

La oss ta en titt på hovedfilen, index.rst, som inneholder hierarkiet til dokumentasjonen din; nemlig innholdsfortegnelsen treet eller toctree.

Åpne den med et tekstredigeringsprogram:

vi index.rst

Når du ser gjennom filen, vil du legge merke til en seksjon som heter toctree. Hvis du har andre kildefiler ( *.rst) for dokumentasjonen din, må du spesifisere dem i toctreeseksjonen: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Det er viktig å:

• La en tom rad over inndataene dine.
• Ikke suffiks kildefilene dine med .rst.
• Plasser kildefilene i deres respektive rekkefølge.
• Bruk kun ett filnavn per rad.
• Innrykk filnavnene dine med :maxdepth: 2.

Når du har fullført endringene, lagrer du filen og avslutter tekstredigeringsprogrammet.

ESC
:!wq

Trinn 5: Lag kildefiler spesifisert ovenfor

Kildefilene må opprettes med navn som samsvarer med det som tidligere er spesifisert i index.rst, ellers vil de ikke inkluderes i den endelige utgangen.

Alle kildefilene må være kompatible med reStructuredText markup language. For mer informasjon, se reStructuredText Primer .

Trinn 6: Skriv ut HTML-versjonen av dokumentasjonen

Når du er ferdig med å komponere dokumentasjonen, kan du skrive ut arbeidet ditt HTML format ved å utføre kommandoen nedenfor:

make html

Utdataene vil bli lagret i katalogen ./\_build/htmlsom inneholder alt som er nødvendig for å vise filen i en nettsurfing.

Dette avslutter veiledningen vår.