API management for documentation
Currently we are using sphinx autosummary
with recursive
option to generate the iota2 API.
The main advantage is that it is fully automated. The API changes are automatically detected and removing or renaming a module no required any intervention in the documentation.
The main drawback is that autosummary
imports every module, that implies iota2 to be installed in the documentation generation environment.
This imposes that the API correspond to the one installed in the conda environment when the API is generated: currently develop.
Then the API between master
and develop
are the same, as autosummary
not support natively versioning.
Currently there are two issues with the online documentation:
- the API between master and develop are different. Maybe linked to the modification on
conf.py
done recently. - The API on
master
branch should display a warning or be not displayed.
To solve this issue: