search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.6k stars 2.12k forks source link

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

Open scolby33 opened 8 years ago

scolby33 commented 8 years ago

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 commented 8 years ago

Hi,

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

simonklb commented 7 years ago

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 commented 6 years ago

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)?