ebben a cikkben, mi lesz megy keresztül a (nagyon) alapjait generál dokumentáció docstrings a Python kódot. Ez egy kicsit őrlés, de miután egyszer megcsinálta, könnyű lesz megismételni a folyamatot minden új projektben.

céljainkhoz feltételezzük, hogy Ön (1) hisz a kód dokumentálásának értékében; (2) docs-t kíván létrehozni a dokstringjeiből, és (3) úgy döntött, hogy a Sphinx-et használja a munka elvégzéséhez.

végül feltételezzük, hogy már beállított egy különálló virtuális környezetet az alkalmazásához. Az érdeklődők számára nagyon szeretem a pyenv környezetvédelmi menedzsert. Még egy praktikus telepítővel is rendelkezik.

telepítenie kell a sphinx-et a pipsegítségével. Legalább szüksége lesz az 1.3 verzióra, de ha nincs jó oka, telepítenie kell a legfrissebb verziót.

$ pip install sphinx

2.lépés: Állítsa be a projektet a Quickstart

a sphinx csomag telepítésekor számos parancssori segédprogram is be van állítva.

az egyik, sphinx-quickstart gyorsan létrehoz egy alapvető konfigurációs fájlt és könyvtárszerkezetet a Dokumentációhoz.

futtassa ezt a parancsot a projekt alapkönyvtárában (azaz a Git repo gyökérben). Számos kérdést fog feltenni Önnek, amelyek meghatározzák a cselekedeteit. Általában elfogadhatja az alapértelmezett értékeket, de itt van néhány javaslat arra, hogy mikor térjen el az alapértelmezettől:

a program futtatása után észreveszi, hogy egy új ./docs mappa létezik a projekt könyvtárában. Ezen kívül három új fájl van a mappában: conf.pyindex.rstésMakefile.

3. lépés: a conf.py File

Az alapértelmezett conf.py a quickstart segédprogram által generált fájl körülbelül 170 sor hosszú, tehát itt nem foglalom bele az egészet. Vannak azonban néhány elem, amelyet frissíteni kell a folytatás előtt.

mondja el a Sphinxnek a Python csomag helyét

az első dolog, amit meg kell tennünk, hogy jelezzük, hogy a Python csomag, amely tartalmazza a programkódot, a conf.py fájlhoz kapcsolódik. Ha a könyvtár szerkezete így néz ki:

Meg kell, hogy jelezze a conf.py fájl Szfinx kell menni a “fel” egy könyvtár szinten, hogy megtalálja a Python csomag.

a hely, hogy ez a végén az első szakasz a konfigurációs fájl. A General Configuration beállítások előtt ezt láthatja:

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

ha nem kommentálták, azt jelzi, hogy a csomag ugyanabban a könyvtárban van, mint a conf.py fájl. Ezt meg kell változtatnia:

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

Add hozzá a” Napoleon ” – ot a Szfinx kiterjesztések listájához, amelyeket a

a dobozból kivéve a Szfinx csak a hagyományos reStructuredText-ben írt docstringeket érti. Ha már a, ahem, kiváltság dolgozik ilyen docstrings, tudni fogja, hogy ők a fájdalom, hogy írjon, és egyáltalán nem emberbarát olvasni, ha nézi őket közvetlenül a forráskódot.

a Napoleon kiterjesztés lehetővé teszi a Sphinx számára, hogy megértse a két másik népszerű formátumban írt docstringeket: a NumPy és a Google.

mindössze annyit kell tennünk, hogy asphinx.ext.napoleon – t hozzáadjuk aextensions listához. Ha kész, akkor így kell kinéznie:

extensions = 

4.lépés: frissítési index.rst

Ezen a ponton valóban futtathatjuk a build folyamatot a dokumentációnk létrehozásához. De elég kiábrándító lenne. Itt van, amit kapnánk:

amennyire szeretném, ha a Sphinx megkeresné nekünk a kikötőinket, és szépen elrendezné őket további konfiguráció nélkül, nem annyira varázslatos.

az előrelépéshez kisebb módosításokat kell végrehajtanunk a index.rst fájlunkon, amely jelenleg így néz ki:

kezdjük azzal, hogy megszabadulunk a tetején található megjegyzéstől, amely csak zaj:

most, bár számos dolgot tehetünk itt, a lehető legkisebbre korlátozzuk magunkat, hogy ezt a bejegyzést kissé ésszerű hosszúságúra tartsuk.

látja, hogy .. toctree:: sor? Ezt nevezi a Szfinx irányelvnek. Hozzá kell adnunk az autodoc irányelveket a index.rst fájlhoz, hogy a Sphinx tudja, milyen kódobjektumokat szeretnénk használni az autodoc kiterjesztést.

előre megyek hozzá, jelezve, hogy a Szfinx, hogy azt akarom, hogy a dokumentum a nyilvánosság tagjai a main.py modul be a my_project csomag:

5. Lépés: Írd meg A Docstrings

nem Fogjuk fedezni, hogyan kell írni docstrings a Numpy vagy a Google stílusú, ez a poszt.

azonban itt található a main.py kód, amely néhány egyszerű NumPy stílusú docstringet tartalmaz, amelyeket az autodoc irányelvünk felvesz:

div >

6. lépés: Generálja a Docs!

most itt az ideje, hogy élvezd a munkád jutalmát. Győződjön meg róla, hogy a ./docs könyvtárba, majd futtasd le a következő: make html

Ha már a következő végig eddig, akkor valami ilyesmit kell látnunk:

amíg látja, hogy dicsőséges build succeeded üzenet végén, készen állsz, hogy íme, a gyönyörű teremtés.

a parancssorban hajtsa végre aopen _build/html/index.html parancsot (vagy csak manuálisan nyissa meg az oldalt a böngészőjében), és látnia kell valami hasonlót:

következő lépések

épp most karcoltuk meg a felületet, és rengeteg szemölcs van még az egyszerű dokumentációban.

a témáról szóló következő bejegyzésben mélyebbre ásunk az autodoc kiterjesztés irányelveiben, és jobban ellenőrizzük dokumentációnk tartalmát és megjelenését.