Можно ли скрыть аргументы функции Python в Sphinx?

Предположим, что у меня есть следующая функция, которая задокументирована в стиле Numpydoc, и документация автоматически сгенерирована с помощью Sphinx директива autofunction:

def foo(x, y, _hidden_argument=None):
    """
    Foo a bar.

    Parameters
    ----------
    x: str
        The first argument to foo.
    y: str
        The second argument to foo.

    Returns
    -------
    The barred foo.

    """
    if _hidden_argument:
        _end_users_shouldnt_call_this_function(x, y)
    return x + y

Я не хочу рекламировать скрытый аргумент как часть моего общедоступного API, но он появляется в моей автоматической сгенерированной документации. Есть ли способ сказать Sphinx игнорировать конкретный аргумент функции или (еще лучше) сделать это автоматически игнорировать аргументы с лидирующим подчеркиванием?

Ответ 1

Я не думаю, что в Sphinx есть вариант. Один из возможных способов сделать это без необходимости взломать код - это использовать настраиваемую подпись.

В этом случае вам нужно что-то вроде:

.. autofunction:: some_module.foo(x, y)

Это переопределит список параметров функции и спрячет ненужный аргумент в документе.

Ответ 2

Можно редактировать сигнатуру функции в обработчике события autodoc-process-signature.

Параметр signature обработчика событий содержит подпись; строка формы (parameter_1, parameter_2). В приведенном ниже фрагменте split() используется для удаления последнего параметра функции:

hidden = "_hidden_argument"

def process_sig(app, what, name, obj, options, signature, return_annotation):
    if signature and hidden in signature:
        signature = signature.split(hidden)[0] + ")" 
    return (signature, return_annotation)

def setup(app):
    app.connect("autodoc-process-signature", process_sig)

В результате документация покажет подпись функции в вопросе как foo(x, y) вместо foo(x, y, _hidden_argument=None).

Ответ 3

Я согласен, что это, вероятно, признак плохого дизайна - но я только что натолкнулся на случай, когда мне пришлось вставить бесполезный **kwargs аргумент **kwargs просто для удовлетворения проверки статического типа mypy...

Итак, основываясь на предложении mzjn, я опубликовал простое расширение sphix, чтобы скрыть аргументы из документации:

https://pypi.org/project/sphinxcontrib-autodoc-filterparams/