Sphinx is not updating documentation properly
Question:
I am using Sphinx for documenting a python app and I used the sphinx_build_script -b html <path/to/source> <path/to/build> command to build the index.html file. When modifying docstrings and using the same command again, it seams the html content is not updating properly.
I’ve tried deleting every index files from the _modules, _sources and build directories without any luck.
This is the generated html file:
Classe de generation de rapport PDF
:param orientation: Orientation en portrait ou paysage.
:param unit: par defaut en mm.
:param format: Format du document pdf (A4, A6, Letter).
and that is the source code:
"""Classe de generation de rapport PDF
:param orientation: Orientation en portrait ou paysage.
:type orientation: char.
:param unit: par defaut en mm.
:param format: Format du document pdf (A4, A6, Letter).
THIS IS AN UPDATE
"""
After running the build command multiple times in a row, it seams the html file will update 1/5 times.
Answers:
It’s not the right way. You should use apidoc to generate the project first. All the classes/modules that will be added after that should be added manually to the documentation, or through calling apidoc again (although you shouldn’t do that if you’ve customized the originally produced project).
For example the following directive will add a new module and it’s members recursively to the page:
.. automodule:: foo.bar
:members:
:undoc-members:
It’s is not as automatic as JavaDoc, but in some cases it is even better to have at least some control over the docs.
Also, it’s better to use make html instead of whatever you’re using, as it does generate some indices and such. I don’t remember exactly, but I’m positive some stuff isn’t generated, when you do that with bare Sphinx script.
I had this same issue on a package I was developing. If I updated docstrings, removed all build docs, and rebuilt, the API documentation was unchanged. To solve it I had to re-install the package, or install it in editable mode.
pip install -e .
Rebuilding the docs now should show updated documentation.
I am using Sphinx for documenting a python app and I used the sphinx_build_script -b html <path/to/source> <path/to/build> command to build the index.html file. When modifying docstrings and using the same command again, it seams the html content is not updating properly.
I’ve tried deleting every index files from the _modules, _sources and build directories without any luck.
This is the generated html file:
Classe de generation de rapport PDF
:param orientation: Orientation en portrait ou paysage.
:param unit: par defaut en mm.
:param format: Format du document pdf (A4, A6, Letter).
and that is the source code:
"""Classe de generation de rapport PDF
:param orientation: Orientation en portrait ou paysage.
:type orientation: char.
:param unit: par defaut en mm.
:param format: Format du document pdf (A4, A6, Letter).
THIS IS AN UPDATE
"""
After running the build command multiple times in a row, it seams the html file will update 1/5 times.
It’s not the right way. You should use apidoc to generate the project first. All the classes/modules that will be added after that should be added manually to the documentation, or through calling apidoc again (although you shouldn’t do that if you’ve customized the originally produced project).
For example the following directive will add a new module and it’s members recursively to the page:
.. automodule:: foo.bar
:members:
:undoc-members:
It’s is not as automatic as JavaDoc, but in some cases it is even better to have at least some control over the docs.
Also, it’s better to use make html instead of whatever you’re using, as it does generate some indices and such. I don’t remember exactly, but I’m positive some stuff isn’t generated, when you do that with bare Sphinx script.
I had this same issue on a package I was developing. If I updated docstrings, removed all build docs, and rebuilt, the API documentation was unchanged. To solve it I had to re-install the package, or install it in editable mode.
pip install -e .
Rebuilding the docs now should show updated documentation.