Brug Sphinx til at oprette dokumentation i flere formater på CentOS 7

Sphinx er et nyttigt Python-baseret værktøj til teknikere og forfattere, der giver dem mulighed for nemt at skabe elegant, fuldt funktionel dokumentation i forskellige formater. Med Sphinx skriver du dokumenter ved hjælp af reStructuredText - et letvægts opmærkningssprog - for det første, så kan du få outputtet i flere formater, inklusive HTML, LaTeX, PDF, ePub og andre.

I denne vejledning vil vi dække processen med at installere og bruge Sphinxpå en CentOS 7 x64-instans på Vults platform.

Forudsætninger

• En CentOS 7 x64-instans.
• En sudo-bruger .

Trin 1: Opdater systemet

sudo yum update
sudo shutdown -r now

Trin 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

Trin 3: Konfigurer den grundlæggende konfiguration for din dokumentation

Før du begynder at bruge Sphinx, skal du angive din kildemappe, som Sphinxskal køre og gemme al din dokumentation. Når du har oprettet den mappe, du har til hensigt at bruge, kan du køre, sphinx-quickstartsom vil initialisere Sphinxog oprette den nødvendige grundlæggende konfiguration.

sphinx-quickstart ligner en opsætningsguide, som vil stille dig spørgsmål, der bestemmer aspekterne af dit projekt.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Trin 4: Konstruer hierarkiet for din dokumentation

Som standard vil sphinx-quickstartguiden oprette flere mapper 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

Lad os tage et kig på masterfilen, index.rst, som indeholder hierarkiet i din dokumentation; nemlig indholdsfortegnelsen træ eller toctree.

Åbn det med en teksteditor:

vi index.rst

Når du gennemgår filen, vil du bemærke et afsnit kaldet toctree. Hvis du har andre kildefiler ( *.rst) til din dokumentation, skal du angive dem i toctreesektionen: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Det er bydende nødvendigt at:

• Efterlad en tom række over dit input.
• Undlad at suffikse dine kildefiler med .rst.
• Placer dine kildefiler i deres respektive rækkefølge.
• Brug kun ét filnavn pr. række.
• Indryk dine filnavne med :maxdepth: 2.

Når du har gennemført dine ændringer, skal du gemme din fil og afslutte teksteditoren.

ESC
:!wq

Trin 5: Opret kildefiler specificeret ovenfor

Kildefilerne skal oprettes med navne, der matcher det, der tidligere var angivet i index.rst, ellers vil de ikke indgå i det endelige output.

Alle kildefiler skal være kompatible med reStructuredText markup language. For mere information henvises til reStructuredText Primer .

Trin 6: Udskriv HTML-versionen af ​​din dokumentation

Når du er færdig med at komponere din dokumentation, kan du outputte dit arbejde HTML format ved at udføre nedenstående kommando:

make html

Outputtet vil blive gemt i mappen, ./\_build/htmlsom indeholder alt det nødvendige for at se filen i en web-browsing.

Dette afslutter vores tutorial.