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.

Not without knowing what you actually do. Just to clarify: You are using the autodoc extension like described in the Sphinx documentation? Sphinx is not like JavaDoc, per default it does not extract documentation from the programs source code. — BlackJack
– BlackJack, Commented Jul 28, 2014 at 16:39
Yes I am using autodoc and it successfully created the .rst files. The problem is that the html file Sphinx create when running the build command is not up-to-date with my source files.@BlackJack — rndlaine
– rndlaine, Commented Jul 28, 2014 at 17:07

Matthew Tankersley · Accepted Answer · 2022-07-21 23:44:57Z

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.

wswld · Accepted Answer · 2014-07-29 14:32:32Z

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.

Collectives™ on Stack Overflow

Sphinx is not updating documentation properly

2 Answers 2

Comments

Comments

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

Comments

Related