i denne artikel gennemgår vi det (meget) grundlæggende ved at generere dokumentation fra docstrings i din Python-kode. Det er lidt af en slibning, men når du har gjort det en gang, vil det være nemt at gentage processen i hvert nyt projekt.

til vores formål antager vi, at du (1) tror på værdien af at dokumentere din kode; (2) ønsker at generere dokumenter fra dine docstrings og (3) har valgt at bruge Sfinks til at udføre arbejdet.

endelig antages det, at du allerede har konfigureret et særskilt virtuelt miljø til din applikation. For de interesserede kan jeg virkelig godt lide pyenv environment manager. Det har endda en praktisk installatør.

Du skal installere Sfinks viapip. Som minimum skal du bruge version 1.3, men medmindre du har god grund, skal du installere den nyeste version.

$ pip install sphinx

Trin 2: Opsæt dit projekt med Hurtigstart

når du installerer sfinkspakken, er der også en række kommandolinjeværktøjer.

en af dem,sphinx-quickstart vil hurtigt generere en grundlæggende konfigurationsfil og mappestruktur til din dokumentation.

Kør denne kommando i basismappen for dit projekt (dvs.Git repo root). Det vil stille dig en række spørgsmål, der vil afgøre det handlinger. Du kan generelt acceptere standardværdierne, men her er nogle forslag til, hvornår du skal afvige fra standardværdien:

når programmet er kørt, vil du bemærke, at en ny ./docs mappe findes i din projektmappe. Derudover er der tre nye filer i den mappe: conf.pyindex.rst ogMakefile.

Trin 3: Justering af conf.py fil

standardconf.py fil genereret af hurtigstart-værktøjet er omkring 170 linjer lang, så jeg vil ikke medtage det hele her. Der er dog et par ting, som vi skal opdatere, før vi fortsætter.

Fortæl Sfinks placeringen af din Python-pakke

den første ting, vi skal gøre, er at angive, hvor Python-pakken, der indeholder din programkode, er i forhold til conf.py – filen. Hvis din mappestruktur ser sådan ud:

du skal angive i filen conf.py, at Sfinksen skal gå “op” et mappeniveau for at finde Python-pakken.

stedet at sætte dette er i slutningen af den første sektion af konfigurationsfilen. Lige før General Configuration indstillinger, vil du se dette:

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

Hvis det ikke blev kommenteret, ville det indikere, at din pakke er i samme mappe somconf.py filen. Du skal ændre det til dette:

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

Tilføj “Napoleon” til listen over Sfinksudvidelser for at bruge

ud af boksen forstår Sfinks kun docstrings skrevet i traditionel omstrukturerettekst. Hvis du har haft det, ahem, privilegium at arbejde med sådanne docstrings, vil du vide, at de er en smerte at skrive og slet ikke menneskelige venlige at læse, når man ser på dem direkte i kildekoden.Napoleon-udvidelsen gør det muligt for Sfinks at forstå docstrings skrevet i to andre populære formater: NumPy og Google.

alt, hvad vi skal gøre, er at tilføje sphinx.ext.napoleon til extensions liste. Når du er færdig, skal det se sådan ud:

extensions = 

Trin 4: Opdater indeks.rst

på dette tidspunkt kunne vi faktisk køre byggeprocessen for at generere vores dokumentation. Men det ville være ret skuffende. Her er hvad vi ville få:

så meget som jeg gerne vil have, at Sfinks går og finder vores docstrings til os og arrangerer dem pænt uden yderligere konfiguration, er det ikke helt så magisk.

for at komme videre skal vi lave nogle mindre ændringer til voresindex.rst fil, som i øjeblikket ser sådan ud:

lad os starte med at slippe af med kommentaren øverst, som bare er støj:

nu, mens der er en række ting, vi kunne gøre her, vil vi begrænse os til det absolutte minimum for at holde dette indlæg til en noget rimelig længde.

kan du se, at .. toctree:: linje? Det er det, Sfinks kalder et direktiv. Vi er nødt til at tilføje autodoc-direktiver til vores index.rst fil, så Sfinks ved, hvilke kodeobjekter vi ønsker at bruge Autodoc-udvidelsen på.

Jeg vil gå videre og tilføje en, der indikerer til Sfinks, at jeg vil have det til at dokumentere de offentlige medlemmer af minmain.py modul inde imy_projectpakke:

Trin 5: Skriv dine Docstrings

Vi dækker ikke, hvordan man skriver docstrings i Numpy eller Google style i dette indlæg.

men her er koden fra main.py som indeholder et par enkle numpy stil docstrings, der vil blive afhentet af vores autodoc direktiv:

Trin 6: Generer dine dokumenter!

nu er det tid til at høste fordelene ved dit arbejde. Sørg for at du er i ./docs directory og udfør følgende: make html

Hvis du har fulgt med hidtil, skal du se noget som dette:

så længe du ser den herlige build succeeded besked i slutningen er du klar til at gå i gå hen og se din smukke skabelse.

på kommandolinjen skal du udføre open _build/html/index.html (eller bare åbne den side i din bro. ser manuelt), og du skal se noget som dette:

næste trin

vi har lige ridset overfladen her, og der er masser af vorter stadig i vores enkle dokumentation.

i det næste indlæg om dette emne vil vi grave dybere ned i direktiverne i autodoc-udvidelsen og opnå større kontrol med indholdet og udseendet af vores dokumentation.