Page MenuHomeSoftware Heritage
Create Task
Maniphest T1254

Generated API documentation sometimes misses function signatures
Closed, MigratedEdits Locked
Actions

Description

The overall generated sphinx documentation sometimes misses function signatures
(see for instance F3320445, F3320446 or F3320447).

This does not happen all the time but still pretty often based on my tests.
I encounter this issue using Sphinx 1.4.9 (Debian stretch version) but also with the latest version available on PyPI.
I thought it may be due to make parallel jobs but I managed to reproduced it when calling make -j1.

Until a proper fix is found, when one wants to deploy the documentation, he or she should check
that the produced modules' indices documentation look correct before uploading it.

Revisions and Commits

rDWAPPS Web applications
rDWAPPS66b126e46c4f doc_config.SimpleDocumenter: Ensure lower priority than FunctionDocumenter

Event Timeline

anlambert triaged this task as Normal priority.Oct 9 2018, 5:16 PM
anlambert created this task.
zack claimed this task.Oct 10 2018, 1:52 PM
zack added a subscriber: zack.

I see the problem in your screenshots, but right now I cannot find any instance of it in the docs deployed at docs.s.o.
Please let me know if/when you find one.
Also, next time you can reproduce it locally it would be great if you can paste somewhere the full log of your sphinx build.

I suspect this is some kind of parse error due to non aligned sphinx versions, but I've no better clue than that for now.

anlambert added a comment.Oct 10 2018, 1:54 PM

I reuploaded the documentation yesterday so that's why you won't find the issue I mentioned.
I will post a trace of the doc build where the error occurs.

anlambert added a comment.Oct 10 2018, 4:13 PM

Took some time to dig into the verbose output of sphinx when the problem occurs and found the cause of it.

Turns out that the blame is on me for this one. When I removed the swh-web api documentation duplication,
I added a custom autodoc documenter in order to remove function signature and doc content indentation [1].
The corresponding directive is .. autosimple:: <function>. The purpose is to only display the doc generated
with sphinxcontrib.httpdomain in the api endpoints documentation (see for instance [2]).

But when autodoc tries to generate the documentation for a particular Python object (function in our case),
it first gets a list of compatible documenters and picks the one with highest priority [3].
As I did not modify the priority of my custom documenter, it has the same as the base one used
to document functions and so it could get picked instead.

So setting a priority to my custom documenter lower than the one for the default function
documenter is the proper fix here.

[1] https://forge.softwareheritage.org/rDWAPPS988c88f9896de4216f2274a264d882977ddad2d3#change-4JZ7aJqwPyTr
[2] https://forge.softwareheritage.org/source/swh-web/browse/master/docs/uri-scheme-api-origin.rst
[3] https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/autodoc/__init__.py#L654-L666

anlambert closed this task as Resolved by committing rDWAPPS66b126e46c4f: doc_config.SimpleDocumenter: Ensure lower priority than FunctionDocumenter.Oct 10 2018, 4:16 PM
anlambert added a commit: rDWAPPS66b126e46c4f: doc_config.SimpleDocumenter: Ensure lower priority than FunctionDocumenter.
gitlab-migration changed the task status from Resolved to Migrated.Jan 8 2023, 4:25 PM
gitlab-migration claimed this task.
gitlab-migration added a subscriber: gitlab-migration.

This task has been migrated to GitLab.

About · Developer information · Legal