Sphinx Autodoc remove empty submodules and packages

Question

I'm trying to use sphinx in order to create a documentation for my project, it is a bunch of functions divided to modules inside the project.

I need only a small subset of the functions to be exposed in the documentation so I used autodoc-skip-member to filter out what is not needed by tagging the docstring and it seems to work by not listing the unneeded functions but I end up with a bunch of empty modules and submodules.

Is there a way to tell sphinx to not list the empty modules? I assume I can use the exclude feature but then it will not be an automated process to add new code, I will have to maintain the exclude list all the time.

I'm using this flow to generate the HTML docs:

sphinx-apidoc -f -e -M -o source/ ../src/
sphinx-build source/ build/

This is the code the filter out the functions in the conf.py file, even when it returns True on a module it is listed in the final HTML doc.

def include_only(app, what, name, obj, skip, options):
    if obj.__doc__ is not None and "::public" in obj.__doc__:
        return False
    return True


def setup(app):
    app.connect('autodoc-skip-member', include_only)

Answer 1

When you run sphinx-apidoc, it runs using predetermined options, these being 'members', 'undoc-members', 'show-inheritance'. These can be seen in the generated .rst files as you will see something like this:

.. automodule:: module
   :members:
   :undoc-members:
   :show-inheritance:

With 'undoc-members' as an option, autodoc will add in empty modules into your documentation. To get around this, when you run sphinx-apidoc, you simply prepend with SPHINX_APIDOC_OPTIONS=members,show-inheritance (plus any other autodoc options you wish to include), i.e.

SPHINX_APIDOC_OPTIONS=members,show-inheritance sphinx-apidoc ...