V tomto článku budeme jít přes (velmi) základy generování dokumentace z docstrings v jazyce Python kód. Je to trochu grind, ale poté, co to uděláte jednou, bude snadné opakovat proces v každém novém projektu.

pro naše účely budeme předpokládat, že (1) věříte v hodnotu dokumentace vašeho kódu; (2) chcete generovat dokumenty z vašich dokumentů a (3) jste se rozhodli použít Sphinx k provedení práce.

nakonec se předpokládá, že jste již nastavili odlišné virtuální prostředí pro vaši aplikaci. Pro zájemce se mi opravdu líbí Správce prostředí pyenv. Má dokonce šikovný instalační program.

budete muset nainstalovat sphinx přes pip. Minimálně budete potřebovat verzi 1.3, ale pokud nemáte dobrý důvod, měli byste nainstalovat nejnovější verzi.

$ pip install sphinx

Krok 2: Nastavení Projektu s Quickstart

Při instalaci sfinga balíček číslo z příkazového řádku nástroje jsou nastaveny stejně.

jeden z nich, sphinx-quickstart rychle vygeneruje základní konfigurační soubor a adresářovou strukturu pro vaši dokumentaci.

spusťte tento příkaz v základním adresáři vašeho projektu (tj. To vám položí řadu otázek, které určí, že je to akce. Lze obecně přijmout výchozí hodnoty, ale zde jsou některé návrhy, když se odchýlit od výchozí:

Poté, co program má spustit, zjistíte, že nový ./docs složka existuje v adresáři projektu. Kromě toho jsou v této složce tři nové soubory: conf.pyindex.rst aMakefile.

Krok 3: Nastavení conf.py Souboru

výchozí conf.py soubor generovaný quickstart utility je asi 170 linek dlouho, takže nebude obsahovat celou věc zde. Existuje však několik položek, které musíme před pokračováním aktualizovat.

Říct, Sfinga Umístění vašeho Balíčku Python

první věc, kterou musíme udělat, je uvést, kde Python balíček, který obsahuje váš kód programu je ve vztahu k conf.py soubor. Pokud vaše adresářová struktura vypadá takto:

Budete muset uvést v conf.py souboru, že Sfinga musí jít „nahoru“ o jednu úroveň adresáře najít Python balíček.

místo, které chcete umístit, je na konci první části konfiguračního souboru. Těsně před nastavením General Configuration uvidíte toto:

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

Pokud to nebylo komentováno, znamená to, že váš balíček je ve stejném adresáři jako soubor conf.py. Musíte změnit to, aby toto:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Přidat „Napoleon“ na seznam Sphinx Rozšíření Použití

po Vybalení z krabice, Sfinga, pouze chápe docstrings napsán v tradiční reStructuredText. Pokud jste měli, ehm, čest pracovat s takovými docstrings, budete vědět, že jsou bolesti psát a vůbec ne lidské přátelské číst, když se na ně dívám přímo ve zdrojovém kódu.

rozšíření Napoleon umožňuje Sphinx pochopit dokumenty napsané ve dvou dalších populárních formátech: NumPy a Google.

Vše, co musíme udělat, je přidat sphinx.ext.napoleonextensions seznam. Až budete hotovi, mělo by to vypadat takto:

extensions = 

Krok 4: aktualizovat index.rst

v tomto okamžiku bychom mohli skutečně spustit proces sestavení a vygenerovat naši dokumentaci. Ale bylo by to docela zklamání. Tady je to, co bychom dostali:

stejně Jako já bych rád, Sfinga jít a najít naše docstrings pro nás a uspořádat je pěkně bez jakékoliv další konfigurace, to není tak docela magické.

abychom se posunuli vpřed, budeme muset provést některé drobné úpravy našeho souboru index.rst, který v současné době vypadá takto:

začněme tím, jak se zbavit komentář na vrcholu, který je jen hluk:

Teď, zatímco existuje řada věcí, které můžeme udělat, budeme omezit na minimum, aby tento příspěvek poněkud přiměřené délce.

vidíte ,že.. toctree:: řádek? Tomu Sfinga říká směrnice. Musíme přidat autodoc směrnic do našeho index.rst souboru tak, že Sfinga ví, co kód objekty chceme použít autodoc příponu na.

budu pokračovat a přidat jeden označující se Sfingou, že chci, aby to dokument veřejné členy mé main.py modul uvnitř my_project balení:

Krok 5: Napište Své Docstrings

nebudeme zahrnovat jak napsat docstrings v Numpy nebo styl Google v tomto příspěvku.

Nicméně, zde je kód main.py, který obsahuje pár jednoduchých NumPy styl docstrings, že bude vyzvednout na naší autodoc směrnice:

Krok 6: Vygenerujte své dokumenty!

nyní je čas sklízet plody své práce. Ujistěte se, že jste v ./docs adresáře a spusťte následující: make html

Pokud jste byli po spolu tak daleko, měl by jsi vidět něco jako toto:

tak dlouho, Jak budete vidět, že slavné build succeeded zpráva na konci, jste připraveni jít a viz své krásné stvoření.

na příkazovém řádku spusťte open _build/html/index.html (nebo jen otevřete tuto stránku v prohlížeči ručně) a měli byste vidět něco takového:

Další postup

Právě jsme poškrábaný povrch tu a tam jsou hodně bradavice stále v naší jednoduché dokumentace.

V další post na toto téma, budeme kopat hlouběji do směrnic autodoc rozšíření a dosažení větší kontrolu obsahu a vzhledu naší dokumentace.