Sphinx coverage generates empty python.txt file

Question

I'm using Sphinx to document my project. I've enabled the sphinx.ext.coverage extension in my configuration file. I'm running the following command to generate the coverage report (as guided by this answer:

bash-3.2$ sphinx-build -v -b coverage . _build/coverage/
Making output directory...
Running Sphinx v1.2.3
loading pickled environment... not yet created
building [coverage]: coverage overview
updating environment: 10 added, 0 changed, 0 removed
...
reading sources... [100%] modules
looking for now-outdated files... none found
pickling environment... done
checking consistency... /some/path/modules.rst:: WARNING: document isn't included in any toctree
done
build succeeded, 17 warnings.

If I look inside _build/coverage/python.txt, all I see is:

Undocumented Python objects
===========================

This isn't quite right, since there are definitely parts of my project that aren't documented.

Somebody posted about this on the sphinx mailing list, but didn't get any replies.

Does anybody know what the problem is? How do I fix it?

Answer 1

One thing to consider -- if you are using :undoc-members:, they will be considered documented, even though they are nothing more than a stub. This was what was causing me to have no results.

Answer 2

If your function has no docstring but is specified in the 'contents' part of your .rst file, then it would still be considered as 'covered' by the coverage builder, and not stand in your python.txt