Ako nastaviť Sphinx na zdokumentovanie kódu Pythonu

Sphinx je jedným z najpopulárnejších nástrojov na generovanie dokumentácie. V celej komunite Pythonu vývojári používajú tento bezplatný softvér s otvoreným zdrojovým kódom. Dokáže extrahovať text priamo z vášho kódu alebo súborov markdown a potom ho použiť na generovanie dokumentácie v rôznych formátoch, ako je obyčajný text, HTML, PDF a EPUB.

Nastavenie Sfingy

Pred nastavením Sphinx sa pozrite na to, čo robí a niektoré z jej hlavných funkcií.

Čo je sfinga a čo robí?

Ako už bolo spomenuté, Sphinx je generátor dokumentácie. V predvolenom nastavení používa značkovací jazyk reStructuredText (RST), ale prostredníctvom rozšírení tretích strán môže použite Markdown, populárny značkovací jazyk pre obyčajný text. Potom prevedie tieto súbory RST alebo markdown do HTML, PDF, manuálových stránok alebo iných formátov, ktoré uprednostňujete.

Niektoré z funkcií, ktoré Sfinga obsahuje, sú:

• Schopnosť generovať dokumentáciu z kódu.
• Schopnosť krížových odkazov na rôzne strany dokumentu pomocou automatických odkazov na funkcie, triedy, citácie a výrazy zo slovníka.
• Zvýraznenie syntaxe pre bloky kódu.
• Podpora pre témy, ktoré môžu zmeniť vzhľad a dojem z dokumentov.
• Jednoduchá definícia stromu dokumentov prostredníctvom obsahu.
• Schopnosť integrovať sa s rozšíreniami tretích strán na pridanie ďalších funkcií do dokumentov, ako sú testovacie úryvky kódu.

Inštalácia Sfingy

Pred inštaláciou Sphinx sa uistite, že máte Python 3 nainštalovaný vo vašom vývojovom prostredí. Potom môžete použiť správcu balíkov pip na inštaláciu Sphinx spustením nasledujúceho príkazu vo vašom termináli:

pip install sphinx

Týmto sa stiahne a nainštaluje Sphinx a jej závislosti.

Po inštalácii spustite v príkazovom riadku nasledovné.

sphinx-build --verzia

Ak všetko fungovalo správne, mali by ste vidieť číslo verzie balíka Sphinx, ktorý ste práve nainštalovali.

Vytvorenie nového projektu Sphinx

Po nainštalovaní Sphinx prejdite do svojho pracovného adresára a spustite príkaz sphinx-quickstart na vytvorenie nového projektu Sphinx.

sfinga-rýchly štart

Tento príkaz vás vyzve, aby ste odpovedali na sériu otázok o tom, ako nakonfigurovať váš projekt Sphinx. Môžete zadať názov projektu a použiť predvolené možnosti pre ostatné otázky. V budúcnosti možno budete chcieť prispôsobiť odpovede na základe vášho projektu.

Ak vypíšete obsah svojho adresára, uvidíte, že tento príkaz vytvorí nejaké súbory za vás. Súbor conf.py obsahuje konfiguračné hodnoty a súbor index.rst slúži ako uvítacia stránka vašej dokumentácie. Adresár zostavenia bude hostiť vygenerovanú dokumentáciu a Sphinx používa súbor Makefile (make.bat na Windows) na vytvorenie dokumentácie.

Písanie dokumentácie pomocou Sfingy

Súbor index.rst v koreňovom adresári vášho adresára je domovskou stránkou vašej aplikácie. Takže ho otvorte pomocou textového editora, ako je VS Code – alebo akýkoľvek iný dobrý bezplatný editor kódu- upraviť ho.

Index.rst môžete zmeniť, ako uznáte za vhodné, ale jedna vec, ktorú by aspoň mal mať, je direktíva root toctree (strom s obsahom). Je to nevyhnutné, pretože spája viacero súborov do jednej hierarchie dokumentov.

Ak chcete pridať dokumentáciu do súboru index.rst, môžete použiť označenie RST.

Ako príklad si predstavte súbor index.rst pre modul math_utils. Tento súbor môže obsahovať stručný prehľad účelu modulu a obsah, ktorý odkazuje na iné stránky dokumentácie.

Vitajte v Math Utils
.. toctree::
 :maxdepth: 2
Začíname

Ak chcete použiť tento modul, budete potrebovať nasledovné:
* Python nainštalovaný.
* Textový editor
Math Utils

Modul `math-utils` poskytuje základné matematické funkcie ako sčítanie a
odčítanie.

Podľa potreby môžete pridať ďalšie súbory .rst. Môžete napríklad vytvoriť príručku príspevkov v súbore s názvom contributing.rst, ktorý obsahuje nasledujúce usmernenia pre príspevky.

Sprievodca prispievaním
Uvítame príspevky do nášho projektu! Tu je niekoľko pokynov pre
prispievanie:
- Fork projektu na GitHub.
- Vykonajte zmeny v novej vetve.
- Napíšte testy, aby ste sa uistili, že vaše zmeny fungujú správne.
- Odošlite žiadosť o stiahnutie s vašimi zmenami.
- Vykonajte požadované zmeny.
Ďakujeme, že ste prispeli!

Potom môžete tento súbor prepojiť z index.rst pridaním novej sekcie do direktívy toctree:

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

 prispievanie

Tým sa v obsahu vytvorí nová položka s názvom prispievanie, ktorá po kliknutí prevedie používateľa na stránku s príspevkami.

Po napísaní dokumentácie je ďalším krokom jej zostavenie. Vytváranie dokumentácie tu znamená generovanie stránok HTML, manuálov alebo PDF zo súborov RST.

Vytváranie dokumentácie

Ak chcete vytvoriť dokumentáciu pomocou Sphinx, budete musieť spustiť príkaz make html v koreňovom adresári vášho priečinka, kde sa nachádza súbor makefile.

urobiť html

V priečinku zostavenia by ste mali vidieť súbory HTML. Ak sa počas zostavovania vyskytli chyby, Sphinx vám to oznámi v termináli.

Ak chcete zobraziť dokumentáciu, otvorte súbor index.html vo svojom prehliadači:

Mali by ste byť schopní navigovať do prispievajúceho sprievodcu z obsahu.

Prispôsobenie dokumentácie

Práve teraz má dokumentácia nejaký základný štýl. Ak si ho chcete prispôsobiť, možno pridaním farieb vašej značky alebo dokonca pridaním tmavého režimu, môžete nainštalovať a používať iné vstavané témy alebo si vytvorte vlastný motív.

Na ukážku skúste zmeniť tému na tému s názvom príroda:

1. Otvorte konfiguračný súbor Sphinx conf.py v adresári vášho projektu Sphinx.
2. Vyhľadajte riadok, ktorý definuje možnosť html_theme, a zmeňte ho na povahu
3. Uložte konfiguračný súbor a znova vytvorte dokumentáciu, aby ste videli svoje zmeny.

Takto by mala vyzerať domovská stránka dokumentácie.

Ak nechcete používať vstavané témy, vždy môžete použiť a motív Sfingy tretej strany namiesto toho.

Dokumentovanie kódu pomocou reťazcov dokumentov

Sphinx generuje vašu Python dokumentáciu z textu, ktorý píšete v súboroch RST. Aj keď to v niektorých prípadoch stačí, možno budete chcieť vo svojom kóde použiť aj reťazce docstrings na úrovni modulu.

Dokumentačné reťazce žijú priamo v zdrojových súboroch vášho projektu. Umožňujú vám opísať, čo kód robí, poskytnúť príklady a dokonca vytvoriť testy pre tieto príklady. Po napísaní reťazcov dokumentov z nich môžete generovať dokumentáciu pomocou Sphinx.