Sphinx napoleon 文档函数可以返回多个参数吗？

Question

我正在尝试使用 Google 代码风格来记录一个函数，然后我使用带有拿破仑扩展名的 sphinx 来为其创建文档。该函数的不寻常之处在于 return 有两个参数。我认为拿破仑不会处理这个问题。如果是这样，有人能告诉我他们是如何处理的吗？

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

也许我收到一条消息说 return 多个参数不是很好的编码风格，但你能做到吗？生成的 html 将这两行视为对一个参数的描述的一部分。如果我在 servers 和 msg 行之间放一个换行符，它会有所帮助，但它仍然记录一个 arg。

Answer 1

Python 只有 returns 一个对象。如果你打电话

serv,msg = foo(myinput)

然后你显式地扩展了 expression_list 元组，它是在函数 returns 中用这段代码

生成的

return servers,msg

你的文档字符串应该读这样的东西（拿破仑 Google 风格）

"""
one line summary

longer explanation

Args:
    a (int): parameter description

Returns:
    (tuple): tuple containing:

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

或者拿破仑 NumPy 风格：

"""
one line summary

longer explanation

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

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

查看 python 文档 return and perhaps expression_list

Answer 2

Google 样式不支持多个 return 值。作为解决方法，您可以使用：

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.

即使每个 returned 项目都有多行描述，这也会产生很好的输出。

Answer 3

在尝试了几种选择后，这种格式适合我

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

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

注意换行后的两个空格。

Answer 4

您可以使用 napoleon_custom_sections 设置配置拿破仑来解释 Google 风格文档字符串的 Returns 部分，就像 Args 部分一样。

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

这样，Sphinx 可以很好地呈现多个 return 值（如问题中给出的）。但是，我不确定在使用此选项时是否仍然严格遵守 Google 风格的文档字符串约定。

Sphinx napoleon 文档函数可以返回多个参数吗？

Can Sphinx napoleon document function returning multiple arguments?

python

python-sphinx

sphinx-napoleon