API doc

Introductie

Net als bijvoorbeeld Java en C++, heeft Python ook de mogelijkheid om documentatie over de code automatisch te genereren. Er zijn veel verschillende manieren, waarbij de tool Sphinx regelmatig genoemd wordt. Doen = leren, vandaar direct voor Sphinx gekozen.

installeren

pip install Sphinx

initialiseren

Gebruik hiervoor een kant en klaar script: sphinx-quickstart

geklier

Sphinx gaat heel snel mis en dan zie je geen doc van je code. Dit is een site met goede instructies:https://sphinx-rtd-tutorial.readthedocs.io/en/latest/index.html Er kan geoefend worden met de bijbehorende Github repo, waaruit de volgende conclusie is getrokken: alle aangehaalde imports moeten bestaan, anders gaat Sphinx op z'n bek. Een klein hikje in het proces en het gaat mis, waardoor er geen enkele docu wordt gegenereerd. Heel irritant, de log wordt ergens ver weg in een dir gedrukt, maar dat had ik wel in moeten kijken. Had veel tijd gescheeld.

Niet mokken, gewoon mocken!

Bij het voorbeeld is dit ook het geval. De BLE import mislukt op Windows, waardoor Sphinx misgaat. Er is iets als een mockup configuratie, dat valt nog eens te testen, om te kijken of je niet alle refs hoeft te verwijderen in de code, zie https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports. Om de mislukte BLE import te onderdrukken voeg je het volgende aan conf.py toe:

autodoc_mock_imports = ['bluepy']

Belangrijk: je moet in index.rst op de juiste manier de docu subpaginas er in hangen, anders zie je wel wat maar ook niet veel.