Подключить Sphinx autodoc-skip-member к моей функции

Я хочу использовать событие sphinx autodoc-skip-member чтобы выбрать часть членов определенного класса Python для документации.

Но из документов sphinx это неясно, и я не могу найти примеры, которые иллюстрируют: где мне поместить код для подключения этого? Я вижу Sphinx.connect и подозреваю, что он мой conf.py, но когда я пробую варианты этого кода в conf.py, я не могу найти объект приложения, который я должен подключить():

def maybe_skip_member(app, what, name, obj, skip,
                                  options):
    print app, what, name, obj, skip, options
    return False

# This is not even close to correct:
#from sphinx.application import Sphinx
#Sphinx().connect('autodoc-skip-member', maybe_skip_member)

Указатель на простой пример был бы идеальным.


python python-sphinx autodoc
person bstpierre    schedule 21.09.2010    source источник

Ответы (3)


arrow_upward
44
arrow_downward

Ага, последнее усилие по гуглению обнаружило этот пример , прокрутите вниз. По-видимому, функция setup() в conf.py будет вызываться вместе с приложением. Я смог определить следующее в нижней части моего conf.py:

def maybe_skip_member(app, what, name, obj, skip, options):
    print app, what, name, obj, skip, options
    return True

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

Что, очевидно, бесполезно (пропускает все), но это минимальный пример, который я искал и не мог найти...

person bstpierre    schedule 21.09.2010

arrow_upward
16
arrow_downward

Этот ответ расширяет ответ bstpierre. Он реализует autodoc-skip-member. Ниже приведена соответствующая часть моего conf.py:

autodoc_default_flags = ['members', 'private-members', 'special-members',
                         #'undoc-members',
                         'show-inheritance']

def autodoc_skip_member(app, what, name, obj, skip, options):
    # Ref: https://stackoverflow.com/a/21449475/
    exclusions = ('__weakref__',  # special-members
                  '__doc__', '__module__', '__dict__',  # undoc-members
                  )
    exclude = name in exclusions
    # return True if (skip or exclude) else None  # Can interfere with subsequent skip functions.
    return True if exclude else None
 
def setup(app):
    app.connect('autodoc-skip-member', autodoc_skip_member)
person Acumenus    schedule 30.01.2014

arrow_upward
2
arrow_downward

Если кто-то ищет тот же вопрос, но для AutoAPI вместо autodoc, приведенный ниже фрагмент успешно исключает все атрибуты и методы из документации, созданной AutoAPI, которые начинаются с _; это не очень хорошая идея на практике, но я хотел начать с чего-то радикального для простоты обнаружения.

def autoapi_skip_member(app, what, name, obj, skip, options):
    """Exclude all private attributes, methods, and dunder methods from Sphinx."""
    import re
    exclude = re.findall('\._.*', str(obj))
    return skip or exclude


def setup(app):
    """Add autoapi-skip-member."""
    app.connect('autoapi-skip-member', autoapi_skip_member)

Одна причуда / странность, на которую следует обратить внимание, заключается в том, что те же функции, применяемые к name вместо str(obj) в функции autoapi_skip_member, похоже, не работают, и я (очевидно) ошибочно полагал, что это одно и то же ('полное имя объекта' согласно документации AutoAPI).

Это включает в себя добавление чего-то вроде приведенного ниже для обнаружения методов, начинающихся с _:

or (hasattr(obj, '__name__') and str(obj.__name__).startswith('_'))
person M.GEM    schedule 31.12.2020