i den här artikeln går vi igenom (mycket) grunderna för att generera dokumentation från docstrings i din Python-kod. Det är lite av en grind, men när du gör det en gång blir det lätt att upprepa processen i varje nytt projekt.

för våra ändamål antar vi att du (1) tror på värdet av att dokumentera din kod; (2) vill generera dokument från dina docstrings och (3), har valt att använda Sfinx för att utföra arbetet.

slutligen antas det att du redan har konfigurerat en distinkt virtuell miljö för din applikation. För dem som är intresserade gillar jag verkligen pyenv environment manager. Det har även en praktisk installatör.

Du måste installera sphinx via pip. Åtminstone behöver du version 1.3, men om du inte har goda skäl bör du installera den senaste versionen.

$ pip install sphinx

steg 2: Konfigurera ditt projekt med Quickstart

När du installerar sphinx-paketet installeras också ett antal kommandoradsverktyg.

en av dessa,sphinx-quickstart genererar snabbt en grundläggande konfigurationsfil och katalogstruktur för din dokumentation.

kör det här kommandot i baskatalogen för ditt projekt (dvs. git repo-roten). Det kommer att ställa dig ett antal frågor som avgör dess handlingar. Du kan i allmänhet Acceptera standardvärdena, men här är några förslag på när du ska avvika från standardvärdet:

När programmet har körts kommer du att märka att en ny ./docs mapp finns i din projektkatalog. Dessutom finns det tre nya filer i den mappen: conf.pyindex.rstochMakefile.

steg 3: Justera conf.py File

standard conf.py – filen som genereras av quickstart-verktyget är cirka 170 rader lång, så jag kommer inte att inkludera det hela här. Det finns dock ett par saker som vi behöver uppdatera innan vi fortsätter.

berätta för Sphinx platsen för ditt Python-paket

det första vi behöver göra är att ange var Python-paketet som innehåller din programkod är i förhållande till filen conf.py. Om din katalogstruktur ser ut så här:

Du måste ange i filenconf.py att Sphinx måste gå ”upp” en katalognivå för att hitta python-paketet.

platsen att sätta detta är i slutet av den första delen av konfigurationsfilen. Strax före General Configuration inställningar ser du detta:

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

om det inte kommenterades skulle det indikera att ditt paket finns i samma katalog som filen conf.py. Du måste ändra det till detta:

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

Lägg till ”Napoleon” i listan över Sphinx-tillägg för att använda

utanför rutan förstår Sphinx bara docstrings skrivna i traditionell reStructuredText. Om du har haft, ahem, privilegiet att arbeta med sådana docstrings, vet du att de är en smärta att skriva och inte alls mänsklig vänlig att läsa när man tittar på dem direkt i källkoden.

Napoleon-tillägget gör det möjligt för Sphinx att förstå docstrings skrivna i två andra populära format: NumPy och Google.

allt vi behöver göra är att lägga tillsphinx.ext.napoleon tillextensions listan. När du är klar ska det se ut så här:

extensions = 

steg 4: Uppdateringsindex.rst

Vid denna tidpunkt kunde vi faktiskt köra byggprocessen för att generera vår dokumentation. Men det skulle vara ganska nedslående. Här är vad vi skulle få:

så mycket som jag skulle vilja att Sphinx skulle gå och hitta våra docstrings för oss och ordna dem snyggt utan någon ytterligare konfiguration, är det inte riktigt så magiskt.

För att gå vidare måste vi göra några mindre ändringar av vår index.rst – fil, som för närvarande ser ut så här:

Låt oss börja med att bli av med kommentaren högst upp som bara är buller:

nu, medan det finns ett antal saker som vi kan göra här, kommer vi att begränsa oss till det minsta för att hålla detta inlägg till en något rimlig längd.

ser du att.. toctree:: linje? Det är vad Sfinx kallar ett direktiv. Vi måste lägga till autodoc-direktiv till vår index.rst – fil så att Sphinx vet vilka kodobjekt vi vill använda Autodoc-tillägget på.

Jag ska gå vidare och lägga till en som indikerar för Sphinx att jag vill att den ska dokumentera de offentliga medlemmarna i mittmain.py modul inutimy_project paket:

Steg 5: Skriv dina Docstrings

Vi kommer inte att täcka hur man skriver docstrings i Numpy eller Google-stil i det här inlägget.

men här är koden från main.py som innehåller ett par enkla NumPy style docstrings som kommer att hämtas av vårt autodoc-direktiv:

steg 6: Skapa dina dokument!

Nu är det dags att skörda frukterna av ditt arbete. Se till att du är i katalogen ./docs och kör följande: make html

om du har följt med hittills, bör du se något så här:

så länge du ser det härliga build succeeded meddelandet i slutet är du redo att göra det här:

så länge du ser det härliga build succeeded gå och se din vackra skapelse.kör

på kommandoraden open _build/html/index.html (eller bara öppna den sidan i din webbläsare manuellt) och du bör se något liknande:

nästa steg

vi har just repat ytan här och det finns många vårtor fortfarande i vår enkla dokumentation.

i nästa inlägg om detta ämne kommer vi att gräva djupare i direktiven för autodoc-tillägget och uppnå större kontroll över innehållet och utseendet på vår dokumentation.