Переопределение псевдонима автодока Sphinx для импорта частного класса?

У меня есть пакет Python, который я пытаюсь задокументировать с помощью sphinx-autodoc. В моем пакете python есть __init__.py файл, который импортирует класс из подмодуля, чтобы сделать его доступным на уровне пакета.

from a.b.c.d import _Foo as Foo

__all__ = ["Foo"]

Если я это сделаю, моя (html) документация будет следующей:

Пакет a.b.c

Подмодули

Модуль a.b.c.d

[фрагмент документации нерелевантных общедоступных классов в модуле a.b.c.d]

Содержание модуля

Модуль c.

a.b.c. Фу

псевдоним _Foo

Не очень полезно, поскольку _Foo (справедливо) недокументирован, поскольку это частный класс в подмодуле a.b.c.d.

Я могу добавить к моему conf.py следующее, что гарантирует, что определение класса private в модуле задокументировано.

def skip(app, what, name, obj, skip, options):
    if name == "_Foo":
        return False
    return skip

Другая альтернатива, но не лучшие вещи, которые я пробовал:

  1. Переименуйте a.b.c.d._Foo в a.b.c.d.Foo (а затем обновите импорт до from a.b.c.d import Foo), но затем я получаю документ, задокументированный дважды, один раз в заголовке abcd module и еще раз в разделе Содержимое модуля заголовок.
  2. Переименование a.b.c.d.Foo в a.b.c.d.MyFoo и последующий импорт (from a.b.c.d import MyFoo as Foo) приводит к тому, что MyFoo документируется, а Foo указывается как псевдоним MyFoo.

В идеале я бы хотел, чтобы частное определение оставалось недокументированным, но чтобы версия, импортированная в пакет, была полностью документирована. Кто-нибудь знает, как я могу этого добиться?


python python-sphinx autodoc
person Saff    schedule 04.08.2016    source источник

Ответы (2)


arrow_upward
2
arrow_downward

Sphinx использует члены __name__ и __module__ класса и __module__ член владельца класса, чтобы выяснить, является ли это псевдонимом или настоящим. Вы можете обмануть Sphinx, думая, что ваш импортированный класс - настоящий, явно указав эти члены.

from a.b.c.d import _Foo as Foo
Foo.__module__ = __name__
Foo.__name__ = 'Foo'
person barjak    schedule 21.11.2019
comment
Если вы сделаете это, вы сломаете inspect.getsource(Foo) - person Eric; 27.03.2020
comment
Сделайте это в функции setup в conf.py, и тогда вы не будете ничего путать в исходном исходном коде. Например: github.com/shap.com/shap/blob/6af9e1008702fb0fab939bf2154bf / - person slund; 12.12.2020

arrow_upward
1
arrow_downward

Используя директиву members, вы можете показать все элементы, кроме тех, которые начинаются с '_'. Вы можете оставить _Foo недокументированным в a.b.c.d и задокументировать его как Foo в a.b.c. Я бы импортировал _Foo как from a.b.c.d import _Foo, а затем добавил бы любую документацию, например:

Foo = _Foo
''' blah blah blah '''

Если по какой-то причине вы не хотите, чтобы _Foo в пространстве имен a.b.c, вы также можете сделать:

from a.b.c.d import _Foo as Foo
Foo = Foo
''' blah blah blah '''
person markw    schedule 14.02.2020