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?

Quadri

A great example of this is 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. – Taunt

have you tried something along the lines of :exclude-members: Intermediate? – Taunt

This might be of interest: sphinx-doc.org/en/master/usage/extensions/… (to be included in Sphinx 4.1). Issue: github.com/sphinx-doc/sphinx/issues/3014 – Nodal

Answer 1

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).

Lotte

Answer 2

You can try the following:

Set inheritance as the default in the autodoc configuration:

autodoc_default_options = {
    # other options
    'show-inheritance': True
}

Then on a specific class unset the option:

.. autoclass:: SomeClass :no-show-inheritance:

Lander