Sphinx: Using `:undoc-members:` together with `sphinx.ext.coverage` is confusing

[scolby33]

I am using Sphinx with apidoc and coverage. apidoc automatically includes the :undoc-members: option for its generated source files. This is not a problem in itself, but when combined with sphinx.ext.coverage can lead to confusing behavior.

According to this Stack Overflow answer and personal testing, sphinx.ext.coverage counts members that have been included with :undoc-members: as "documented." This seems to me to be confusing and perhaps unintended.

There are two options for resolving this that I can see:

1. Add an option to sphinx.ext.coverage to ignore members that are only documented via :undoc-members:.
2. Add a warning to sphinx.ext.coverage's documentation pointing out this behavior.

Perhaps both of these should be implemented, but the second is certainly the simpler short-term solution.

EDIT: Note that this applies to using sphinx.ext.coverage without apidoc as well--that situation is only where I came across this problem.

[glyg]

Hi,

I got exactly the same issue, did you find a work-around or is there a patch?

[simonklb]

Came across this as well. Solved it by running sphinx-apidoc with SPHINX_APIDOC_OPTIONS=members and then built the coverage report.

Of course, this will force you to separate building the coverage and other docs if you want to include the undocumented stuff elsewhere.

[baileyparker]

Just ran into this and the suggestion by @simonklb indeed works. Just to clarify, the full incantation is something like:

cd docs; SPHINX_APIDOC_OPTIONS=members sphinx-apidoc -o source ../[your_package]
cd ..; sphinx-build -b coverage docs docs/_build

(Assuming in your index.rst you include source/*, which requires :glob:)

Then, your coverage results are in docs/_build/{c.txt,python.txt,undoc.pickle}.

IMO, this is a pretty foolish default. I'd even go as far to say that this is never what you want when you're running the coverage builder. Would it break anything for sphinx-apidoc's options to default to members when sphinx.ext.coverage is enabled (or maybe when --ext-coverage is passed)?