How can I just list undocumented members with sphinx/autodoc?

Question

I am using sphinx with the autodoc extension, and would like to generate a list only containing the undocumented member functions in several modules, and not the documented members.

I can successfully create a list that includes both documented members and undocumented members as follows:

.. automodule:: module
    :members:
    :undoc-members:

Using the :members: directive alone creates the list of documented members only, as expected.

.. automodule:: module
    :members:

But using just the :undoc-members: directive alone (i.e. omitting the :members: flag) does not result in any list at all:

.. automodule:: module
    :undoc-members:

Is there a way to automatically generate this?

(The primary documentation includes a page that shows all the documented members, but I'd find it far more useful to ensure I have written docs for each function etc by having a single page that lists any undocumented member, without showing the text for those that are documented).

Answer 1

Overriding the autodoc-process-docstring event (as noted by @delnan) can help, by adding the following to conf.py:

# set up the types of member to check that are documented
members_to_watch = ['function',];

def warn_undocumented_members(app, what, name, obj, options, lines):
    if(what in members_to_watch and len(lines)==0):
        # warn to terminal during build
        print "Warning: ", what, "is undocumented: ", name, "(%d)"% len(lines);
        # or modify the docstring so the rendered output is highlights the omission
        lines.append(".. Warning:: %s '%s' undocumented" % (what, name));

And then connect this function to the event (from an answer in this SO thread):

def setup(app):
    app.connect('autodoc-process-docstring', warn_undocumented_members);

To turn on (off) the warnings include (exclude) the undoc-members -- globally with autodoc_default_flags in conf.py, or with both the directives as in the question.

autodoc_default_flags = ['members', 'undoc-members' ]
#autodoc_default_flags = ['members' ]

EDIT:

I attempted to extend this approach to generate just the undoc members, by the following method:

• conditionally set a property, say, warn_undoc=True, on the object during during the function warn_undocumented_members (above)
• attach a second override function to the preprocessor event autodoc-skip-member that skipped all members if they did not have warn_undoc set.

However, further investigation rules this approach out, because autodoc-skip-member occurs for each group of members before autodoc-process-docstring occurs. Thus, the properties are set too late to conditionally skip based on presence/absence of docstrings.