python - 狮身人面像拿破仑文档函数可以返回多个参数吗？

Question

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

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 行之间添加一个换行符，它会有所帮助，但它仍在记录一个 arg。

Answer 1

Python 只返回一个对象。如果你打电话

serv,msg = foo(myinput)

然后，您将显式扩展在函数使用此代码返回时生成的 expression_list 元组

return servers,msg

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

"""
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和可能的expression_list

Answer 2

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.

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

Answer 3

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

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

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

Answer 4

在尝试了几个选项后，这种格式对我有用

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

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

注意换行符后的两个空格。