i denne artikkelen går vi gjennom (veldig) grunnleggende om å generere dokumentasjon fra docstrings i Python-koden din. Det er litt av en grind, men etter at du har gjort det en gang, vil det være enkelt å gjenta prosessen i hvert nytt prosjekt.

for vårt formål vil vi anta at du (1) tror på verdien av å dokumentere koden din; (2) ønsker å generere dokumenter fra docstrings og (3) har valgt å bruke Sphinx til å utføre arbeidet.

Til Slutt antas det at du allerede har satt opp et tydelig virtuelt miljø for søknaden din. For de som er interessert, liker jeg virkelig pyenv environment manager. Den har til og med en praktisk installatør.

du må installere sphinx via pip. I det minste trenger du versjon 1.3, men med mindre du har god grunn, bør du installere den nyeste versjonen.

$ pip install sphinx

Trinn 2: Setup Prosjektet Med Quickstart

når du installerer sphinx pakken en rekke kommandolinjeverktøy er oppsett også.

En av disse,sphinx-quickstart vil raskt generere en grunnleggende konfigurasjonsfil og katalogstruktur for dokumentasjonen din.

Kjør denne kommandoen i basekatalogen til prosjektet ditt (dvs.Git repo root). Det vil stille deg en rekke spørsmål som vil avgjøre det er handlinger. Du kan generelt godta standardverdiene, men her er noen forslag til når du skal avvike fra standard:

etter at programmet har kjørt, vil du legge merke til at en ny./docs mappen finnes i prosjektkatalogen. I tillegg er det tre nye filer i den mappen: conf.pyindex.rstogMakefile.

Trinn 3: Justere conf.py Fil

standard conf.py fil generert av quickstart-verktøyet er omtrent 170 linjer lang, så jeg vil ikke inkludere hele greia her. Det er imidlertid et par elementer som vi må oppdatere før du fortsetter.

Fortell Sphinx Plasseringen Av Python-Pakken

det første vi må gjøre er å angi hvor Python-pakken som inneholder programkoden din er i forhold tilconf.py – filen. Hvis katalogstrukturen din ser slik ut:

Eksempel Prosjektkatalogstruktur

du må angi iconf.pyfilen som sphinx må gå»opp»ett katalognivå for å finne python-pakken.

stedet å sette dette er på slutten av den første delen av konfigurasjonsfilen. Like før General Configuration innstillinger, ser du dette:

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

hvis det ikke ble kommentert, vil det indikere at pakken din er i samme katalog somconf.py – filen. Du må endre den til dette:

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

Legg Til «Napoleon» i Listen Over Sphinx-Utvidelser for å Bruke

Ut av boksen forstår Sphinx bare docstrings skrevet i tradisjonell restrukturertekst. Hvis du har hatt, ahem, privilegium å jobbe med slike docstrings, vet du at de er en smerte å skrive og ikke i det hele tatt menneskelig vennlig å lese når du ser på dem direkte i kildekoden.Napoleon-utvidelsen gjør Det mulig For Sphinx å forstå docstrings skrevet i to andre populære formater: NumPy og Google.

Alt vi trenger å gjøre er å legge til sphinx.ext.napoleon tilextensions listen. Når du er ferdig, skal den se slik ut:

extensions = 

Trinn 4: Oppdater indeks.rst

på dette tidspunktet kunne vi faktisk kjøre byggeprosessen for å generere dokumentasjonen vår. Men det ville være ganske skuffende. Her er hva vi ville få:

Ikke mye her å være begeistret for…

så mye som jeg ønsker for sphinx å gå og finne våre docstrings for oss og ordne dem pent uten videre konfigurasjon, er det ikke helt så magisk.

for å gå videre må vi gjøre noen mindre endringer i vår index.rst fil, som for øyeblikket ser slik ut:

La oss begynne med å bli kvitt kommentaren øverst som bare er støy:

Nå, mens det er en rekke ting vi kan gjøre her, skal vi begrense oss til det minste minimum for å holde dette innlegget til en noe rimelig lengde.

ser du at.. toctree:: linje? Det Er Hva Sphinx kaller et direktiv. Vi må legge til autodoc-direktiver iindex.rst – filen slik at Sphinx vet hvilke kodeobjekter vi ønsker å bruke autodoc-utvidelsen på.

jeg vil gå videre og legge til en som indikerer Til Sphinx at jeg vil at den skal dokumentere de offentlige medlemmene av min main.py modul inne imy_project pakke:

Trinn 5: Skriv Dine Docstrings

Vi vil ikke dekke hvordan du skriver docstrings I Numpy eller Google stil i dette innlegget.

Men her er koden fra main.py som inneholder et par enkle NumPy stil docstrings som vil bli plukket opp av vår autodoc direktiv:

Trinn 6: Generer Dokumentene dine!

nå er det på tide å høste fordelene av arbeidet ditt. Pass på at du er i katalogen ./docs og utfør følgende: make html

hvis du har fulgt med så langt, bør du se noe slikt:

Så lenge du ser den strålende build succeededmelding på slutten, er du klar til å gå og se din vakre skapelse.

på kommandolinjen, utfør open _build/html/index.html (eller bare åpne den siden i nettleseren din manuelt), og du bør se noe slikt:

neste trinn

vi har nettopp skrapet overflaten her, og det er mange vorter fortsatt i vår enkle dokumentasjon.

i neste innlegg om dette emnet vil vi grave dypere inn i direktivene til autodoc-utvidelsen og oppnå større kontroll over innholdet og utseendet til dokumentasjonen vår.