in dit artikel gaan we door de (zeer) basisprincipes van het genereren van documentatie van docstrings in je Python-code. Het is een beetje een grind, maar nadat je het een keer doet, zal het gemakkelijk zijn om het proces te herhalen in elk nieuw project.

voor onze doeleinden zullen we aannemen dat u (1) gelooft in de waarde van het documenteren van uw code; (2) documenten wilt genereren van uw docstrings en (3), hebt gekozen om Sphinx te gebruiken om het werk te volbrengen.

ten slotte wordt aangenomen dat u al een aparte virtuele omgeving voor uw toepassing hebt ingesteld. Voor degenen die geïnteresseerd zijn, Ik hou echt van de pyenv environment manager. Het heeft zelfs een handige installateur.

u moet sphinx installeren via pip. Je hebt minimaal versie 1.3 nodig, maar tenzij je een goede reden hebt, moet je de meest recente versie installeren.

$ pip install sphinx

Stap 2: Uw Project instellen met Quickstart

wanneer u het sphinx-pakket installeert, worden ook een aantal opdrachtregelprogramma ‘ s ingesteld.

Eén van die, sphinx-quickstart zal snel een basisconfiguratiebestand en mappenstructuur voor uw documentatie genereren.

voer dit commando uit in de basisdirectory van je project (dat wil zeggen de git repo root). Het zal je een aantal vragen stellen die de acties zullen bepalen. U kunt over het algemeen de standaardwaarden accepteren, maar hier zijn enkele suggesties voor het afwijken van de standaard:

nadat het programma is uitgevoerd, zult u merken dat er een nieuwe ./docs map bestaat in uw projectmap. Daarnaast zijn er drie nieuwe bestanden in die map: conf.pyindex.rst, enMakefile.

Stap 3: conf.py bestand

het standaard conf.py bestand gegenereerd door de quickstart utility is ongeveer 170 regels lang, dus Ik zal hier niet alles opnemen. Er zijn echter een paar items die we moeten updaten voordat u doorgaat.

vertel Sphinx de locatie van uw Python pakket

het eerste wat we moeten doen is aangeven waar het Python pakket dat uw programma code bevat is in relatie tot het conf.py bestand. Als uw mapstructuur er zo uitziet:

u dient in hetconf.pybestand aan te geven dat Sphinx één directory-niveau “omhoog” moet gaan om het Python-pakket te vinden.

de plaats om dit te plaatsen is aan het einde van de eerste sectie van het configuratiebestand. Net voor de instellingen van General Configuration ziet u dit:

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

als het niet werd uitgecommentarieerd, zou het aangeven dat uw pakket zich in dezelfde map bevindt als het conf.py bestand. U dient het als volgt aan te passen:

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

voeg “Napoleon” toe aan de lijst van Sphinx-extensies om

te gebruiken. Als je het voorrecht hebt gehad om met dergelijke docstrings te werken, Weet je dat ze lastig zijn om te schrijven en helemaal niet menselijk vriendelijk om te lezen als je ze rechtstreeks in de broncode bekijkt.

De Napoleon extensie stelt Sphinx in staat om docstrings geschreven in twee andere populaire formaten te begrijpen: NumPy en Google.

alles wat we moeten doen is sphinx.ext.napoleon toevoegen aan de extensions lijst. Als u klaar bent, ziet het er als volgt uit:

extensions = 

Stap 4: Update index.rst

Op dit moment kunnen we het bouwproces uitvoeren om onze documentatie te genereren. Maar het zou behoorlijk teleurstellend zijn. Dit is wat we zouden krijgen:

zo veel als ik graag zou willen dat Sphinx onze docstrings voor ons gaat zoeken en netjes schikt zonder verdere configuratie, is het niet zo magisch.

om verder te gaan, moeten we enkele kleine aanpassingen doen aan ons index.rst bestand, dat er momenteel zo uitziet:

laten we beginnen met het verwijderen van de opmerking bovenaan die gewoon ruis is:

nu, terwijl er een aantal dingen zijn die we hier kunnen doen, gaan we onszelf beperken tot het absolute minimum om deze post op een redelijk redelijke lengte te houden.

ziet u dat .. toctree:: regel? Dat is wat Sphinx een richtlijn noemt. We moeten autodoc directives toevoegen aan ons index.rst bestand zodat Sphinx Weet op welke code objecten we de Autodoc extensie willen gebruiken.

Ik Ga door en voeg er een toe die aangeeft aan de Sphinx dat Ik wil dat het de publieke leden van mijn main.py module documenteert in de my_project pakket:

Stap 5: schrijf uw Docstrings

We zullen niet ingaan op het schrijven van docstrings in Numpy of Google stijl in dit bericht.

echter, hier is de code van main.py die een paar eenvoudige NumPy stijl docstrings bevat die zullen worden opgepikt door onze autodoc-richtlijn:

Stap 6: Genereer uw documenten!

nu is het tijd om de vruchten van uw arbeid te plukken. Zorg ervoor dat u zich in de ./docs map bevindt en voer het volgende uit: make html

Als u tot nu toe hebt gevolgd, zou u zoiets als dit moeten zien:

zolang u dat glorieuze build succeeded bericht aan het einde ziet, bent u klaar om uw mooie creatie te zien.

voer op de opdrachtregel open _build/html/index.html uit (of open die pagina handmatig in uw browser) en u zou zoiets als dit moeten zien:

volgende stappen

we hebben het oppervlak hier net bekrast en er zijn nog veel wratten in onze eenvoudige documentatie.

in het volgende bericht over dit onderwerp zullen we dieper ingaan op de richtlijnen van de Autodoc extensie en zullen we meer controle krijgen over de inhoud en het uiterlijk van onze documentatie.