Python Docstrings builden

Met de docstrings in je python-code kun je semi-automatisch een API documentatie builden. Voor docstrings gebruiken wij de Google stijl conventie. Klik hier voor een voorbeeld.

Om de Google stijl docstrings te kunnen parsen gebruiken we Napoleon, een Sphinx extensie. Deze download je als volgt in CMD:

pip install sphinxcontrib-napoleon

In je std_conf.py bestand hoor je de Napoleon en Autodoc extensies te appenden als volgt (als het goed is, is dit al gedaan):

extensions.append('sphinx.ext.autodoc')
extensions.append('sphinxcontrib.napoleon')

Je kunt nu in de command line je API documentatie builden. Side note: voor deze stap moet er bij elke module die je wilt builden een (lege) __init__.py zitten.

sphinx-apidoc -f -o destination_folder src_code_path

De destination_folder is de folder waarin de gebouwde .rst bestanden komen te staan. De src_code_path is het pad naar de folder van je source code. Diezelfde src_code_path moet je in je std_conf.py zetten zodat het je code kan vinden (als het goed is, is dit ook al gedaan):

import sys
sys.path.insert(1, src_code_path)

Bij de volgende stap zullen de docstrings daadwerkelijk uit de code geextraheerd worden. Dit doe je door je documentatie als volgt te builden:

sphinx-build -b html source_folder destination_folder

De source_folder is de folder waar de conf.py van sphinx staat (niet hetzelfde als de std_conf.py die in een andere folder zit!). De destination_folder is de folder waarin je je .html bestanden wilt plaatsen.