Многофункциональные сигнатуры в строке документа autodoc-ed - PullRequest
Новая
       23

Многофункциональные сигнатуры в строке документа autodoc-ed

0 голосов
/ 29 мая 2019

Согласно Объявление функции переопределения в autodoc для sphinx (связано с Возможно ли переопределить автодок Sphinx для определенных функций? ), возможно создать альтернативную сигнатуру функциив autodoc, поместив его в первой строке строки документа.Это удобно, но возможно ли сделать то же самое для нескольких подписей?

Моя функция принимает один или два дополнительных аргумента и обрабатывает их по-разному в зависимости от того, есть ли один или два: 

def compare(x, y, *bounds):
    """
    Blah blah blah.

    Blah? Blah! Blah Blah.

    Parameters
    ----------
    x :
        Foo.
    y :
        Bar.
    exact :
        One arg.
    lower :
        First of two args.
    upper :
        Second of two args.
    """

Как следует из раздела Parameters, у меня есть два соглашения о вызовах (на самом деле три, так как пустое значение bounds является допустимым):

  1. compare(x, y[, exact])
  2. compare(x, y[, lower, upper])

Я хотел бы включить обе опции в строку документации, во многом как встроенную функцию max.Единственная проблема заключается в том, что max задокументировано с директивой .. function:: вместо .. autofunction::.

Я могу сделать что-то вроде следующего: 

"""compare(x, y[, {exact | lower, upper}])
Blah blah blah.
...

Однако я не думаю, что это предпочтительнее.Позволяет ли autodoc включать несколько строк сигнатур функций в строку документации?

Незначительное примечание: на практике я использую .. automethod:: вместо .. autofunction:: в предположении, что они ведут себя одинаково по отношению к этой конкретной вещи.В маловероятном случае, если это не так, поправьте меня.

...