Может ли sphinx наполеон документировать функцию, возвращающую несколько аргументов?

Я пытаюсь использовать стиль кода Google для документирования функции, для которой я затем использую sphinx с расширением napoleon для создания документации. Функция необычна тем, что возвращает два аргумента. Я не думаю, что Наполеон справится с этим. Если так, может кто-нибудь сказать мне, как они справляются с этим?

def foo(a):
'''one line summary

longer explanation

Args:
  a (int): parameter description

Returns:
  servers (list): list of servers to use
  msg (str): logging message string 
'''
pass

Может быть, я получаю сообщение о том, что возвращать несколько аргументов не очень удобно, но вы можете это сделать? Сгенерированный HTML обрабатывает эти две строки как часть описания для одного аргумента. Если я поставлю новую строку между серверами и строкой msg, это поможет, но все равно документирует один аргумент.

Источник

4 ответа

Решение

Python возвращает только один объект. Если вы позвоните

serv,msg = foo(myinput)

Затем вы явно расширяете кортеж expression_list, который генерируется, когда функция возвращается с этим кодом

return servers,msg

Ваша строка документа должна читать что-то вроде этого (в стиле Google Napoleon)

"""
one line summary

longer explanation

Args:
    a (int): parameter description

Returns:
    (tuple): tuple containing:

        servers(list) servers to use
        msg (str): logging message string 
"""

Или в стиле Napoleon NumPy:

"""
one line summary

longer explanation

Parameters
----------
a : int
    parameter description

Returns
-------
servers : list
    servers to use
msg : str
    logging message string 
"""

Взгляните на документы Python для возврата и, возможно, expression_list

Источник

Стиль Google не поддерживает множественные возвращаемые значения. В качестве обходного пути вы можете использовать:

Returns:
        2-element tuple containing

        - **rates** (*array*): the unnormalized rates (just the sum of the
          exponential kernels). To obtain rates in Hz divide the
          array by `2*tau` (or other conventional `x*tau` duration).
        - **nph** (*array*): number of photons in -5*tau..5*tau window
          for each timestamp. Proportional to the rate computed
          with KDE and rectangular kernel.

Это приводит к хорошему выводу даже с многострочным описанием для каждого возвращаемого элемента.

Источник

Вы можете настроить Наполеон на интерпретацию Returns раздел строки документации в стиле Google, такой как Args раздел с использованием napoleon_custom_sections параметр.

      napoleon_custom_sections = [('Returns', 'params_style')]

Таким образом, несколько возвращаемых значений (как указано в вопросе) хорошо отображаются в Sphinx. Однако я не совсем уверен, что при использовании этого параметра все еще строго соблюдается соглашение о строках документации в стиле Google.

Источник

Попробовав несколько вариантов, этот формат у меня сработал.

def foo(a):
    """
    
    Args:
        a (int): parameter description

    Returns:
        - list: 
          parameter description
        - str: 
          logging message string
    """

Обратите внимание на два пробела после переноса строки.

Источник
Другие вопросы по тегам