I'm trying to use Sphinx to document a Python package which contains various sub-packages and sub-modules. I followed the stock Sphinx quickstart script which produced various files with autodoc directives that, in turn, with the html generator, produced a mostly-as-expected first-pass of the docs based on existing docstrings in the code. Cool.
Now enter sphinx.ext.coverage. With the project existing as it does after the "quickstart" script, running sphinx-build -b coverage <other args> doesn't produce any meaningful output at all, just:
Undocumented Python objects
===========================
...with nothing at all below it. I deliberately remove some docstrings to make sure, and sure enough, no warnings.
I thrashed around for a while and eventually tried using the non-autodoc directives, and lo and behold, coverage suddenly appears to work. Sadly, the autodoc functionality is a large part of what makes Sphinx appealing in the first place. But OK, putting in a .. py:module:: directive for each of the modules helps; it appears to make the coverage extension aware of my modules, and from there I start to get entries in my python.txt about members within those modules that don't have docstrings. That's great, but it appears to mean that for coverage to report on a module, that module has to be explicitly, manually declared in the doc files, which kinda reduces the value of a coverage tool (i.e. if I add a new module to the package, it appears it won't be included in the coverage report until I specifically add a directive for it.) So, what I'm seeing is that autodoc seems capable of automatically traversing sub-modules/packages, but coverage does not.
Question: Am I missing something? The inability to automatically discover new code appearing in a project seems like a pretty glaring fault for a "coverage" tool. It seems to me like a standard coverage tool ought to be opt-out, not opt-in.
As I pushed further, I found even yet more evidence that coverage and autodoc aren't friends. For instance, even when declaring modules manually with .. py:module:: directives (as described above), I find that coverage is not picking up on things like autodoc's exclude-members directive. This directive, as expected, elides matching members from the generated output when building HTML, but coverage still reports those members as undocumented in its coverage report. From my reading
Question: Is this incompatibility between coverage and autodoc noted somewhere in the docs that I've not been able to find? Or, again, am I missing something?
