Skip Empty Modules - Sphinx Autodoc

Question

I am using Sphinx to build documentation for a package. I can't find a way to skip (remove) empty submodules when building doc. Example in Section 2 there is a subsection named Submodule which is blank I want to skip such subsections. I tried using the following code.

def skip_util_classes(app, what, name, obj, skip, options):
    if what == "Submodules":
        skip = True
    return skip


def setup(sphinx):
    sphinx.connect("autodoc-skip-member", skip_util_classes)

The above code is not eliminating section Submodules.

I want to know how can I define a section or subsection that needs to be skipped? And how can I define empty section or subsection that I want to skip in skip_util_classes?

`autodoc-skip-member` cannot be used to remove sections from .rst files. Why do you have empty sections in the first place? — mzjn, Jun 20 '21 at 06:58
When I use `sphinx-apidoc -f -o ` to create .rst file it creates headings as `Subpackages` which is empty and I want to avoid such empty headings when creating .rst files — Lopez, Jun 20 '21 at 09:33
Two ideas: 1) Create a custom sphinx-apidoc template. See https://stackoverflow.com/a/57520238/407651. 2) Don't run sphinx-apidoc over and over again. Run the tool once, fix the output and add it to source control. See https://stackoverflow.com/a/28481785/407651. — mzjn, Jun 20 '21 at 10:21
That was helpful. Could you tell when to use `skip_util_classes`? Why is it not applicable in this case? — Lopez, Jun 20 '21 at 13:02

score 1 · Accepted Answer · answered Jun 21 '21 at 15:42

Something like the skip_util_classes function (a handler for the autodoc-skip-member event) is used when you want Sphinx to ignore certain members of Python modules or classes. See Connect Sphinx autodoc-skip-member to my function.

This technique cannot be used to skip or remove sections in generated .rst files. Here are two suggestions that might help with that problem:

Create a custom sphinx-apidoc template. See Remove the word "module" from Sphinx documentation.
Don't run sphinx-apidoc over and over again. Run the tool once, tweak the output and add it to source control. See Keeping the API updated in Sphinx.

Skip Empty Modules - Sphinx Autodoc

1 Answers1