În acest articol, vom trece prin elementele de bază (foarte) de generare a documentației de la docstrings în codul Python. Este un pic de măcinare, dar după ce o faceți o dată, va fi ușor să repetați procesul în fiecare proiect nou.

pentru scopurile noastre, vom presupune că (1) credeți în valoarea documentării codului dvs.; (2) doriți să generați documente din docstrings și (3) ați ales să utilizați Sphinx pentru a realiza lucrarea.

în cele din urmă, se presupune că ați configurat deja un mediu virtual distinct pentru aplicația dvs. Pentru cei interesați, îmi place foarte mult managerul de mediu pyenv. Are chiar și un instalator la îndemână.

va trebui să instalați sphinx prinpip. Cel puțin veți avea nevoie de versiunea 1.3, dar dacă nu aveți motive întemeiate, ar trebui să instalați cea mai recentă versiune.

$ pip install sphinx

Pasul 2: configurarea proiectului cu Quickstart

când instalați pachetul sphinx un număr de utilitare de linie de comandă sunt de configurare, de asemenea.

unul dintre acestea,sphinx-quickstart va genera rapid un fișier de configurare de bază și o structură de directoare pentru documentația dvs.

rulați această comandă în directorul de bază al proiectului dvs. (adică rădăcina git repo). Vă va pune o serie de întrebări care vor determina acțiunile sale. În general, puteți accepta valorile implicite, dar iată câteva sugestii despre când să vă abateți de la valorile implicite:

după ce programul a rulat, veți observa că există un nou folder./docs în directorul de proiect. În plus, există trei fișiere noi în acel folder:conf.pyindex.rst șiMakefile.

Pasul 3: ajustarea conf.py fișier

implicitconf.py fișier generat de utilitarul quickstart este de aproximativ 170 de linii lungi, așa că nu va include totul aici. Cu toate acestea, există câteva elemente pe care trebuie să le actualizăm înainte de a continua.

spuneți Sphinx locația pachetului Python

primul lucru pe care trebuie să-l facem este să indicăm unde este pachetul Python care conține codul programului dvs. în raport cu fișierulconf.py. Dacă structura dvs. de directoare arată astfel:

exemplu structura directorului proiectului

va trebui să indicați în fișierulconf.py că Sfinxul trebuie să meargă „în sus” cu un nivel de director pentru a găsi pachetul Python.

locul pentru a pune acest lucru este la sfârșitul primei secțiuni a fișierului de configurare. Chiar înainte de setărileGeneral Configuration, veți vedea acest lucru:

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

dacă nu a fost comentat, ar indica faptul că pachetul dvs. se află în același director cu fișierul conf.py. Va trebui să-l schimbe la acest lucru:

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

adăugați „Napoleon” la lista de extensii Sfinx pentru a utiliza

din cutie, Sfinx înțelege doar docstrings scrise în reStructuredText tradițional. Dacă ați avut, ahem, privilegiul de a lucra cu astfel de docstrings, veți ști că acestea sunt o durere de a scrie și nu la toate prietenos umane pentru a citi atunci când se uită la ele direct în codul sursă.extensia Napoleon permite Sphinx să înțeleagă docstrings scrise în alte două formate populare: NumPy și Google.

tot ce trebuie să facem este să adăugămsphinx.ext.napoleon la listaextensions. Când ați terminat, ar trebui să arate astfel:

extensions = 

Pasul 4: Index de actualizare.rst

În acest moment, am putea rula procesul de construire pentru a genera documentația noastră. Dar ar fi destul de dezamăgitor. Iată ce vom obține:

nu de mult aici pentru a fi încântat de…

oricât de mult mi-aș dori ca Sphinx să meargă și să ne găsească docstrings-urile și să le aranjeze frumos fără nicio altă configurație, nu este chiar atât de magic.

pentru a merge mai departe, va trebui să facem câteva modificări minore la fișierul nostru index.rst, care în prezent arată astfel:

să începem prin a scăpa de comentariul din partea de sus, care este doar zgomot:

acum, deși există o serie de lucruri pe care le-am putea face aici, ne vom limita la minimul necesar pentru a menține această postare la o lungime oarecum rezonabilă.

vedeți că.. toctree:: linie? Aceasta este ceea ce Sfinxul numește o directivă. Trebuie să adăugăm directive autodoc la fișierul nostru index.rst, astfel încât Sphinx să știe ce obiecte de cod dorim să folosim extensia autodoc.

voi merge mai departe și adăugați unul indicând Sfinxului că vreau să documenteze membrii publici ai main.py modulul din interiorul my_project pachet:

Pasul 5: scrieți Docstrings

nu vom acoperi cum să scrieți docstrings în stil Numpy sau Google în acest post.

cu toate acestea, aici este codul de la main.py care conține o pereche de docstrings stil NumPy simplu, care va fi preluat de Directiva noastră autodoc:

Pasul 6: Generați-vă documentele!

acum este timpul să culegi recompensele muncii tale. Asigurați-vă că vă aflați în directorul ./docs și executați următoarele: make html

Dacă ați urmărit până acum, ar trebui să vedeți ceva de genul:

atâta timp cât vedeți acel glorios build succeeded mesaj la sfârșit, sunteți gata să du-te și privește frumoasa ta creație.

la linia de comandă, executați open _build/html/index.html (sau pur și simplu deschideți pagina respectivă în browserul dvs. manual) și ar trebui să vedeți ceva de genul acesta:

următorii pași

tocmai am zgâriat suprafața aici și există o mulțime de negi încă în documentația noastră simplă.

în următoarea postare pe această temă, vom aprofunda directivele extensiei autodoc și vom obține un control mai mare asupra conținutului și aspectului documentației noastre.