Sphinx autodoc show-inheritance: How to skip undocumented, intermediate bases?

Question

I have a three-layered class structure like this:

class Super(object):
    """This class is documented."""

class Intermediate(Super):
    pass

class Sub(Intermediate):
    """This is also documented."""

My index.rst file looks as follows:

.. automodule:: mymodule
   :show-inheritance:
   :inherited-members:

Sphinx generates a nice API documentation for me. It includes the classes Super and Sub, with the appropriate comments. It does not include Intermediate, because it doesn't have a comment and I did not supply the undoc-members flag. This is because I don't want Intermediate to show up in the documentation.

My problem is this: Because I supply the show-inheritance flag, Sphinx displays the bases for each class; object for Super and Intermediate for Sub. Since Intermediate is undocumented, I do not want it to show up in the list of base classes. Instead, I'd like Sphinx to display the next documented class up in the inheritance tree, Super. In other words: I want Sphinx to display Super, not Intermediate as the base class of Sub.

Does anybody know how to do this?

A great example of this is [`pyserial`](http://pythonhosted.org/pyserial/). I extended `serial.Serial`, which is just a front for one of the concrete implementations for each supported platform. I wanted the docs to show `serial.Serial` as my base, but instead it shows something like `serial.posixserial.Serial`, with no link since it is not officially documented. — Mad Physicist, Aug 16 '17 at 19:15
have you tried something along the lines of `:exclude-members: Intermediate`? — Mad Physicist, May 31 '18 at 16:29
This might be of interest: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#event-autodoc-process-bases (to be included in Sphinx 4.1). Issue: https://github.com/sphinx-doc/sphinx/issues/3014 — mzjn, Jun 30 '21 at 03:16

score 3 · Answer 1 · answered Feb 14 '19 at 17:54

For this peculiar situation, where you want to "hide" the class inheritance, you can use autoclass to document each visible class instead of documenting the whole module.

For instance:

.. currentmodule:: demo

.. autoclass:: Super
   :members:

.. autoclass:: Sub
   :members:

Then you can add the :show-inheritance: flag to show inheritace to the class you want.

Quoting the doc:

The automodule, autoclass and autoexception directives also support a flag option called show-inheritance. When given, a list of base classes will be inserted just below the class signature (when used with automodule, this will be inserted for every class that is documented in the module).

Sphinx autodoc show-inheritance: How to skip undocumented, intermediate bases?

1 Answers1