3

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)
mzjn
  • 48,958
  • 13
  • 128
  • 248
Amir Rossert
  • 1,003
  • 2
  • 13
  • 33
  • One option is to adjust the output from sphinx-apidoc and then add the *.rst files that you want to keep to source control. There is no requirement to run sphinx-apidoc every time you want to generate documentation. See https://stackoverflow.com/a/28481785/407651. – mzjn Dec 08 '20 at 07:58

1 Answers1

2

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 ...
mw120988
  • 21
  • 2