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

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

你的docstring应该读一些这样的东西(拿破仑谷歌风格)

"""
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文档,也许还有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

您可以将 napoleon 配置为解释ReturnsGoogle 样式文档字符串的部分，例如Args使用该napoleon_custom_sections设置的部分。

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

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