Použite Sphinx na vytváranie dokumentácie vo viacerých formátoch na CentOS 7

Sphinx je užitočný nástroj založený na Pythone pre technikov a spisovateľov, ktorý im umožňuje jednoducho vytvárať elegantnú, plne funkčnú dokumentáciu v rôznych formátoch. So Sphinxom píšete dokumenty pomocou reStructuredText – ľahkého značkovacieho jazyka – na začiatok, potom môžete získať výstup vo viacerých formátoch vrátane HTML, LaTeX, PDF, ePub a ďalších.

V tomto návode sa budeme zaoberať procesom inštalácie a používania Sphinxna inštancii CentOS 7 x64 na platforme Vult.

Predpoklady

• Inštancia CentOS 7 x64.
• Sudo používateľ .

Krok 1: Aktualizujte systém

sudo yum update
sudo shutdown -r now

Krok 2: Nainštalujte pip a Sphinx

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

Krok 3: Nastavte základnú konfiguráciu pre vašu dokumentáciu

Predtým, ako začnete používať Sphinx, musíte špecifikovať váš zdrojový adresár, v ktorom Sphinxsa spustí a uloží všetka vaša dokumentácia. Po vytvorení adresára, ktorý chcete použiť, môžete spustiť, sphinx-quickstartčo inicializuje Sphinxa vytvorí požadovanú základnú konfiguráciu.

sphinx-quickstart je podobný sprievodcovi nastavením, ktorý vás vyzve na otázky určujúce aspekty vášho projektu.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Krok 4: Vytvorte hierarchiu pre vašu dokumentáciu

V predvolenom nastavení sphinx-quickstartsprievodca vytvorí niekoľko adresárov a súborov.

_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

Pozrime sa na hlavný súbor index.rst, ktorý obsahuje hierarchiu vašej dokumentácie; menovite strom obsahu alebo toctree.

Otvorte ho pomocou textového editora:

vi index.rst

Pri prezeraní súboru si všimnete sekciu s názvom toctree. Ak máte ďalšie zdrojové súbory ( *.rst) pre vašu dokumentáciu, budete ich musieť špecifikovať v toctreesekcii: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Je nevyhnutné:

• Nad vstupom ponechajte prázdny riadok.
• Nepripájajte k zdrojovým súborom príponu .rst.
• Umiestnite zdrojové súbory v príslušnom poradí.
• Použite iba jeden názov súboru na riadok.
• Odsadenie názvov súborov pomocou :maxdepth: 2.

Po dokončení úprav uložte súbor a ukončite textový editor.

ESC
:!wq

Krok 5: Vytvorte zdrojové súbory špecifikované vyššie

Zdrojové súbory musia byť vytvorené s názvami, ktoré sa zhodujú s tým, čo bolo predtým špecifikované v index.rst, inak nebudú zahrnuté do konečného výstupu.

Všetky zdrojové súbory musia byť kompatibilné s reStructuredText markup language. Viac informácií nájdete v reStructuredText Primer .

Krok 6: Výstup HTML verzie vašej dokumentácie

Po dokončení zostavovania dokumentácie môžete svoju prácu HTML format vytlačiť vykonaním nižšie uvedeného príkazu:

make html

Výstup sa uloží do adresára, ./\_build/htmlktorý obsahuje všetko potrebné na prezeranie súboru pri prehliadaní webu.

Týmto končíme náš návod.