CODEWITHSUNDEEP
pythoninheritancepython-sphinx
Aran-Fey
Aran-Fey

Reputation: 43146

How can I prevent Sphinx from listing "object" as a base class?

I have this class:

class Class:
    pass

The documentation generated by sphinx (in case it matters, I used the autodoc extension) looks like this:

class package.Class

     Bases: object

The inheritance from object isn't useful information for the reader, and therefore I don't want it in my documentation. The output I'd like to see is this:

class package.Class

Is there a way to exclude object from the list of base classes?

Upvotes: 15

Views: 3326

Answers (5)

kp2pml30
kp2pml30

Reputation: 53

According to Sphinx docs since version 4.1 following is possible in conf.py:

def setup(app):
    def handle_bases(app, name, obj, options, bases: list):
        if object in bases:
            bases.remove(object)
    app.connect('autodoc-process-bases', handle_bases)

Note that it will leave you with empty Bases: line. You can use other answers to filter this out

Upvotes: 0

Alexander Shavykin
Alexander Shavykin

Reputation: 81

As for Jun 2022 and Sphinx v5.0.1, Aran-Fey's answer is a bit outdated; the solution that worked in my case was replace this line:

line_to_delete = _('Bases: %s') % ':class:`object`'

with this:

line_to_delete = _('Bases: %s') % ':py:class:`object`'

Upvotes: 3

PerchunPak
PerchunPak

Reputation: 11

For me, worked really simple solution.

from sphinx.ext import autodoc

class MockedClassDocumenter(autodoc.ClassDocumenter):
    def add_line(self, line: str, source: str, *lineno: int) -> None:
        if line == "   Bases: :py:class:`object`":
            return
        super().add_line(line, source, *lineno)

autodoc.ClassDocumenter = MockedClassDocumenter

In the conf.py.

Upvotes: 1

Aran-Fey
Aran-Fey

Reputation: 43146

This is actually deeply embedded in the autodoc source code, with no way to turn it off:

bases = [b.__module__ in ('__builtin__', 'builtins') and
         u':class:`%s`' % b.__name__ or
         u':class:`%s.%s`' % (b.__module__, b.__name__)
         for b in self.object.__bases__]
self.add_line(u'   ' + _(u'Bases: %s') % ', '.join(bases), sourcename)

object isn't given any special treatment; there's no builtin way to exclude it from the list.

The best (automatic) solution I could find was to monkeypatch autodoc.

Adding this to conf.py enables the desired behavior:

# ClassDocumenter.add_directive_header uses ClassDocumenter.add_line to
#   write the class documentation.
# We'll monkeypatch the add_line method and intercept lines that begin
#   with "Bases:".
# In order to minimize the risk of accidentally intercepting a wrong line,
#   we'll apply this patch inside of the add_directive_header method.

from sphinx.ext.autodoc import ClassDocumenter, _

add_line = ClassDocumenter.add_line
line_to_delete = _(u'Bases: %s') % u':class:`object`'

def add_line_no_object_base(self, text, *args, **kwargs):
    if text.strip() == line_to_delete:
        return

    add_line(self, text, *args, **kwargs)

add_directive_header = ClassDocumenter.add_directive_header

def add_directive_header_no_object_base(self, *args, **kwargs):
    self.add_line = add_line_no_object_base.__get__(self)

    result = add_directive_header(self, *args, **kwargs)

    del self.add_line

    return result

ClassDocumenter.add_directive_header = add_directive_header_no_object_base

Upvotes: 13

hoefling
hoefling

Reputation: 66231

Disclaimer: This may not be the best or most elegant solution, because the more plain classes you have (that subclass object only), the more work you will have to do as you have to preprocess each class manually.

If you are using autoclass directive to document the class, simply don't use the :show-inheritance: option. If you are using automodule to generate documentation for all module members, turning :show-inheritance: off will not help as no base classes will be documented for each class in module. Thus, I would go with the following:

Step 1: Document the class outside of the module without :show-inheritance: like this:

my\.mod module
--------------

.. automodule:: my.mod
   :members:
   :undoc-members:
   :show-inheritance:

.. autoclass:: Class
   :members:
   :undoc-members:

Step 2: Filter class Class out of module's automodule documentation in your conf.py via autodoc-skip-member hook:

def skip_some_classes(app, what, name, obj, skip, options):
    return skip or name in ('Class',)  # define some better condition here

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

This way, all module members except Class will be processed with :show-inheritance: option, while Class is treated separately.

Upvotes: 1

Related Questions