Sphinx: Missing doc for test_*.py
Hello, as Hakan explained I generate the API reference docu via cd common/doc-dev && make html It seems to me that the py-files in common/test/* are ignored. But I can't find an ignore directive in the conf.py (IMHO the central Sphinx config file). Can someone help here? Another tiny wish: Can we add Graphviz based inheritance diagrams in that docu? Kind Christian
It seems to me that the py-files in common/test/* are ignored. But I can't find an ignore directive in the conf.py
The generation of the API doc is hidden behind the "autodoc" extension in the config: https://github.com/bit-team/backintime/blob/master/common/doc-dev/conf.py#L3... It generates API docs for "docstrings" in the source code by importing the modules via python. Example of docstring: https://github.com/bit-team/backintime/blob/master/common/snapshots.py#L50 How docstrings work: https://www.pythonforbeginners.com/basics/python-docstrings By default, autodoc will not generate document for the members that are private, not having docstrings, inherited from super class, or special members. See: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html Since the unit test files do not contain any docstring they are not contained in the Sphinx/autodoc API documentation. I think this is OK, unit tests provide NO API that shall be used by developers but behave like a client that uses the API "under test" The documentation of unit tests should is a complete separate thing to document (from high level test strategy to mid-level test stages to low level inline help to understand the "object under test" and test scenarios...)
Thanks for the feedback. On 2022-09-10 20:08 python@altfeld-im.de wrote:
By default, autodoc will not generate document for the members that are private, not having docstrings, inherited from super class, or special members.
In the current config it seems that private and undocumented members are documented also.
Since the unit test files do not contain any docstring they are not contained in the Sphinx/autodoc API documentation.
Currently I try to document them to improve the understanding for me and ohter developers. Sphinx ignore not only that docstrings but the whole module.
I think this is OK, unit tests provide NO API that shall be used by developers but behave like a client that uses the API "under test"
I don't agree. The API argument doesn't fit here. BIT does not provide an api to the public. The purpose of the Sphinx docu (I would name it "reference docu") is not to "document an API". It is just a way to document code or to make the code docu in the sources files "easier" or more comfortable to read and browse via HTML files. Especially in a multi-person project everything should be documented without exceptions. in a perfect world this would be done by easy to read and self explaining code ("cleancode"). But in most cases it also helps to add some docstrings and # comments.
On Sat, 2022-09-10 at 20:36 +0000, c.buhtz@posteo.jp wrote:
By default, autodoc will not generate document for the members that are private, not having docstrings, inherited from super class, or special members.
In the current config it seems that private and undocumented members are documented also.
I didn't check this but I think the default behaviour of autodoc can be changed in the *.rst files itself, eg. here: https://github.com/bit-team/backintime/blob/master/common/doc-dev/backintime... mainly the autodoc directives :members: :undoc-members:
Sphinx ignores [...] the whole module.
Sphinx creates only documentation for the source code in the location declared via the conf file (relative to the location of the conf.py file): https://github.com/bit-team/backintime/blob/master/common/doc-dev/conf.py#L2... sys.path.insert(0, os.path.abspath(os.path.join(os.pardir))) # adds "backintime/common/doc-dev/.." So only "backintime/common" is considered ATM. To add the unit tests folder add a line to the conf.py: sys.path.insert(0, os.path.abspath("../test")) Then create a new *.rst file for each test_.py file named like the filename (without *.py). I have briefly tried this with backintime/common/doc-dev$ sphinx-apidoc --ext-autodoc -o . .. which should recursively crawl through all source code folders in .. but it didn't quite work as expected (creating one rst file for each *.py module). Instead I got a single test.rst for all unit test that I had to add to the index.rst file to be navigable from the index. Perhaps someone finds a working solution for adding ALL *.py files in all project (sub) folders to Sphinx/autodoc and add this command sequence as new make target in doc-dev. https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html
I don't agree. The API argument doesn't fit here. BIT does not provide an api to the public. The purpose of the Sphinx docu (I would name it "reference docu") is not to "document an API". It is just a way to document code or to make the code docu in the sources files "easier" or more comfortable to read and browse via HTML files.
OK, I understand - this is a valid use case of the documentation :-)
participants (3)
-
c.buhtz＠posteo.jp -
J. A. -
python＠altfeld-im.de