Použijte Sphinx k vytvoření dokumentace ve více formátech na CentOS 7

Sphinx je užitečný nástroj pro techniky a spisovatele založený na Pythonu, který jim umožňuje snadno vytvářet elegantní, plně funkční dokumentaci v různých formátech. Se Sphinxem píšete dokumenty pomocí reStructuredText – lehkého značkovacího jazyka – pro začátečníky, pak můžete získat výstup v různých formátech, včetně HTML, LaTeX, PDF, ePub a dalších.

V tomto tutoriálu se budeme zabývat procesem instalace a používání Sphinxna instanci CentOS 7 x64 na platformě Vult.

Předpoklady

• Instance CentOS 7 x64.
• Uživatel sudo .

Krok 1: Aktualizujte systém

sudo yum update
sudo shutdown -r now

Krok 2: Nainstalujte 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í konfiguraci pro vaši dokumentaci

Než začnete používat Sphinx, musíte zadat zdrojový adresář, ve kterém se Sphinxbude spouštět a ukládat veškerá vaše dokumentace. Jakmile vytvoříte adresář, který hodláte použít, můžete spustit, sphinx-quickstartkterý inicializuje Sphinxa vytvoří požadovanou základní konfiguraci.

sphinx-quickstart je podobný průvodci nastavením, který vás vyzve k otázkám určujícím aspekty vašeho projektu.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Krok 4: Vytvořte hierarchii pro vaši dokumentaci

Ve výchozím nastavení sphinx-quickstartprůvodce vytvoří několik adresářů a souborů.

_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

Podívejme se na hlavní soubor index.rst, který obsahuje hierarchii vaší dokumentace; jmenovitě strom obsahu nebo toctree.

Otevřete jej pomocí textového editoru:

vi index.rst

Při prohlížení souboru si všimnete sekce nazvané toctree. Pokud máte další zdrojové soubory ( *.rst) pro vaši dokumentaci, budete je muset zadat v toctreesekci: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Je nutné:

• Ponechte prázdný řádek nad zadáním.
• Nepřipojujte ke zdrojovým souborům příponu .rst.
• Umístěte zdrojové soubory v příslušném pořadí.
• Použijte pouze jeden název souboru na řádek.
• Odsaďte názvy souborů pomocí :maxdepth: 2.

Po dokončení úprav uložte soubor a ukončete textový editor.

ESC
:!wq

Krok 5: Vytvořte zdrojové soubory specifikované výše

Zdrojové soubory musí být vytvořeny s názvy, které odpovídají tomu, co bylo dříve zadáno v index.rst, jinak nebudou zahrnuty do konečného výstupu.

Všechny zdrojové soubory musí být kompatibilní s reStructuredText markup language. Další informace naleznete v tématu reStructuredText Primer .

Krok 6: Vytiskněte HTML verzi vaší dokumentace

Jakmile dokončíte sestavení dokumentace, můžete svou práci vydat HTML format provedením níže uvedeného příkazu:

make html

Výstup se uloží do adresáře, ./\_build/htmlkterý obsahuje vše potřebné pro prohlížení souboru při prohlížení webu.

Tím náš tutoriál končí.