Jak nastavit Sphinx, aby zdokumentoval váš kód Python

Sphinx je jedním z nejpopulárnějších nástrojů pro generování dokumentace. V celé komunitě Pythonu vývojáři používají tento bezplatný a open source software. Dokáže extrahovat text přímo z vašeho kódu nebo souborů markdown a poté jej použít ke generování dokumentace v různých formátech, jako je prostý text, HTML, PDF a EPUB.

Nastavení Sfingy

Než Sphinx nastavíte, podívejte se, co dělá a jaké jsou jeho hlavní funkce.

Co je sfinga a co dělá?

Jak již bylo zmíněno, Sphinx je generátor dokumentace. Ve výchozím nastavení používá značkovací jazyk reStructuredText (RST), ale prostřednictvím rozšíření třetích stran může také použijte Markdown, oblíbený značkovací jazyk pro prostý text. Poté převede tyto soubory RST nebo markdown do HTML, PDF, manuálových stránek nebo jiných formátů, které preferujete.

Některé z funkcí, které Sphinx zahrnuje, jsou:

• Schopnost generovat dokumentaci z kódu.
instagram viewer
• Schopnost odkazovat na různé stránky dokumentu pomocí automatických odkazů na funkce, třídy, citace a termíny ve slovníku.
• Zvýraznění syntaxe pro bloky kódu.
• Podpora témat, která mohou změnit vzhled a dojem z dokumentů.
• Snadná definice stromu dokumentu pomocí obsahu.
• Schopnost integrovat se s rozšířeními třetích stran a přidat do dokumentů další funkce, jako jsou testovací úryvky kódu.

Instalace Sfingy

Před instalací Sphinx se ujistěte, že máte Python 3 nainstalovaný ve vašem vývojovém prostředí. Poté můžete použít správce balíčků pip k instalaci Sphinx spuštěním následujícího příkazu ve vašem terminálu:

pip install sphinx

Tím se stáhne a nainstaluje Sphinx a jeho závislosti.

Po instalaci spusťte na příkazovém řádku následující.

sphinx-build --verze

Pokud vše fungovalo dobře, měli byste vidět číslo verze balíčku Sphinx, který jste právě nainstalovali.

Vytvoření nového projektu Sphinx

Jakmile nainstalujete Sphinx, přejděte do svého pracovního adresáře a spusťte příkaz sphinx-quickstart pro vytvoření nového projektu Sphinx.

sfinga-rychlý start

Tento příkaz vás vyzve k zodpovězení řady otázek, jak nakonfigurovat váš projekt Sphinx. Můžete zadat název projektu a použít výchozí možnosti pro ostatní otázky. V budoucnu možná budete chtít přizpůsobit odpovědi na základě vašeho projektu.

Pokud vypíšete obsah svého adresáře, uvidíte, že tento příkaz vytvoří nějaké soubory za vás. Conf.py obsahuje konfigurační hodnoty a index.rst slouží jako uvítací stránka vaší dokumentace. Adresář sestavení bude hostit vygenerovanou dokumentaci a Sphinx používá soubor Makefile (make.bat na Windows) k sestavení dokumentace.

Psaní dokumentace pomocí Sphinx

Soubor index.rst v kořenovém adresáři vašeho adresáře je domovskou stránkou vaší aplikace. Otevřete jej tedy pomocí textového editoru, jako je VS Code – nebo jakýkoli jiný dobrý bezplatný editor kódu- upravit to.

Index.rst můžete změnit, jak uznáte za vhodné, ale jedna věc, kterou by alespoň měl mít, je direktiva root toctree (strom s obsahem). To je nezbytné, protože spojuje více souborů do jedné hierarchie dokumentů.

Chcete-li přidat dokumentaci do souboru index.rst, můžete použít označení RST.

Jako příklad zvažte soubor index.rst pro modul math_utils. Tento soubor může obsahovat stručný přehled účelu modulu a obsah, který odkazuje na další stránky dokumentace.

Vítejte v Math Utils
.. toctree::
 :maxdepth: 2
Začínáme

K použití tohoto modulu budete potřebovat následující:
* Python nainstalován.
* Textový editor
Math Utils

Modul `math-utils` poskytuje základní matematické funkce, jako je sčítání a
odčítání.

Podle potřeby můžete přidat další soubory .rst. Můžete například vytvořit průvodce příspěvky v souboru s názvem contributing.rst obsahujícího následující pokyny pro příspěvky.

Přispívající průvodce
Vítáme příspěvky do našeho projektu! Zde jsou některé pokyny pro
přispívající:
- Fork projektu na GitHubu.
- Proveďte změny na nové větvi.
- Napište testy, abyste se ujistili, že vaše změny fungují správně.
- Odešlete žádost o stažení se svými změnami.
- Proveďte požadované změny.
Děkujeme za příspěvek!

Tento soubor pak můžete propojit z index.rst přidáním nové sekce do direktivy toctree:

.. toctree::
 :maxdepth: 2
 :caption: Obsah

 přispívající

Tím se v obsahu vytvoří nová položka s názvem přispívající, která po kliknutí uživatele přenese na stránku s příspěvky.

Jakmile napíšete dokumentaci, dalším krokem je její sestavení. Zde sestavení dokumentace znamená generování HTML, manuálových nebo PDF stránek ze souborů RST.

Vytváření dokumentace

Chcete-li vytvořit dokumentaci pomocí Sphinx, budete muset spustit příkaz make html v kořenovém adresáři vaší složky, kde je umístěn soubor makefile.

vytvořit html

Ve složce sestavení byste měli vidět soubory HTML. Pokud se během sestavování vyskytly chyby, Sphinx vás o tom informuje v terminálu.

Chcete-li zobrazit dokumentaci, otevřete ve svém prohlížeči soubor index.html:

Měli byste být schopni přejít do přispívajícího průvodce z obsahu.

Přizpůsobení dokumentace

Právě teď má dokumentace nějaký základní styl. Pokud si jej chcete přizpůsobit, třeba přidáním barev vaší značky nebo dokonce přidáním tmavého režimu, můžete nainstalovat a používat jiné vestavěná témata nebo si vytvořte vlastní motiv.

Chcete-li to demonstrovat, zkuste změnit téma na téma zvané příroda:

1. Otevřete konfigurační soubor Sphinx conf.py v adresáři projektu Sphinx.
2. Vyhledejte řádek, který definuje volbu html_theme, a změňte ji na přirozenou
3. Uložte konfigurační soubor a znovu vytvořte dokumentaci, abyste viděli své změny.

Takto by měla vypadat domovská stránka dokumentace.

Pokud nechcete používat vestavěná témata, můžete vždy použít a téma Sfingy třetí strany namísto.

Dokumentování kódu pomocí Docstrings

Sphinx generuje vaši dokumentaci Pythonu z textu, který napíšete do souborů RST. I když to v některých případech stačí, můžete také chtít použít docstrings ve svém kódu na úrovni modulu.

Dokumentační řetězce žijí přímo ve zdrojových souborech vašeho projektu. Umožňují vám popsat, co kód dělá, poskytnout příklady a dokonce pro tyto příklady vytvořit testy. Jakmile napíšete dokumentační řetězce, můžete z nich pomocí Sphinx generovat dokumentaci.