Sphinx autodoc show-inheritance: Как пропустить недокументированные, промежуточные базы?

У меня есть трехуровневая структура класса:

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

class Intermediate(Super):
    pass

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

Мой файл index.rst выглядит следующим образом:

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

Sphinx создает для меня хорошую документацию по API. Он включает классы Super и Sub с соответствующими комментариями. Он не включает Intermediate, потому что в нем нет комментария, а я не указал флаг undoc-members. Это потому, что я не хочу, чтобы Intermediate отображалось в документации.

Моя проблема заключается в следующем: поскольку я указываю флаг show-inheritance, Sphinx отображает базы для каждого класса; object вместо Super и Intermediate вместо Sub. Поскольку Intermediate недокументирован, я не хочу, чтобы он отображался в списке базовых классов. Вместо этого я бы хотел, чтобы Sphinx отображал следующий задокументированный класс в дереве наследования, Super. Другими словами: я хочу, чтобы Sphinx отображал Super, а не Intermediate в качестве базового класса Sub.

Кто-нибудь знает, как это сделать?


person Michael Herrmann    schedule 22.06.2013    source источник
comment
Отличным примером этого является pyserial. Я расширил serial.Serial, который является лишь прикрытием для одной из конкретных реализаций для каждой поддерживаемой платформы. Я хотел, чтобы документы отображали serial.Serial в качестве моей базы, но вместо этого он показывает что-то вроде serial.posixserial.Serial без ссылки, так как это официально не задокументировано.   -  person Mad Physicist    schedule 16.08.2017
comment
вы пробовали что-то вроде :exclude-members: Intermediate?   -  person Mad Physicist    schedule 31.05.2018
comment
Это может представлять интерес: sphinx-doc.org/en/master/usage/extensions/ (будет включено в Sphinx 4.1). Проблема: github.com/sphinx-doc/sphinx/issues/3014   -  person mzjn    schedule 30.06.2021


Ответы (1)


В этой специфической ситуации, когда вы хотите «скрыть» наследование класса, вы можете использовать autoclass для документирования каждого видимого класса вместо документирования всего модуля.

Например:

.. currentmodule:: demo

.. autoclass:: Super
   :members:

.. autoclass:: Sub
   :members:

Затем вы можете добавить флаг :show-inheritance:, чтобы показать наследование нужному классу.

Цитирую документ:

Директивы automodule, autoclass и autoexception также поддерживают параметр флага, называемый show-inheritance. При задании список базовых классов будет вставлен сразу под сигнатурой класса (при использовании с автомодулем он будет вставлен для каждого класса, задокументированного в модуле).

person Laurent LAPORTE    schedule 14.02.2019