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

Question

我正在尝试使用Google代码风格来记录一个函数，然后使用sphinx和napoleon扩展创建文档。该函数返回两个参数，这在使用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将这两行视为一个参数的描述部分。如果我在servers和msg之间加入换行符，它会有帮助，但仍然是记录一个参数。

- MrCartoonology

---

相关问题：在Google风格的文档字符串中使用多个返回值 #9119 - Mateen Ulhaq

Answer 1

Python 只返回一个对象。如果你调用

serv,msg = foo(myinput)

那么，当函数返回此代码时，您正在明确扩展生成的 expression_list 元组。

return servers,msg

你的文档字符串应该像这样读起来（使用Napoleon 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 
"""

或者使用 Napoleon NumPy 风格：

"""
one line summary

longer explanation

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

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

看看Python文档中的return和可能涉及到的表达式列表

- mor22

---

我不确定这是否是OP所指的，但如果你有一个像if foo: return foo else: return bar这样的函数呢？ - Railslide

是的，这很模糊。原帖作者应该发布一些代码来澄清。 - mor22

谢谢！这正是我要找的，也很有道理。可能最好将返回类型记录为元组，而不是像我以为的那样直接跳到元组元素的描述，但我无法完全使其工作（我目前对sphinx几乎没有经验）。描述服务器和消息的两行确实会在一个新缩进的行上开始，但不会解析这些行，它们被视为一个段落。我能否让sphinx/napoleon为元组元素引入与Args参数相同类型的格式？ - MrCartoonology

你可能需要在它们之间添加一行额外的代码；我已经更新了上面的示例。我没有使用Google风格。我知道Numpy风格支持多个返回值。请查看http://sphinxcontrib-napoleon.readthedocs.org/en/latest/index.html#google-vs-numpy。 - mor22

看起来Google风格不支持多返回值：https://bitbucket.org/birkenfeld/sphinx-contrib/issues/111/napoleon-multiple-returns-indentations - Ilya Etingof

@MrCartoonology 我在每个元组元素前使用破折号将它们转换为项目符号列表。在我使用的ReadTheDocs样式中，它们现在看起来与参数类似。 - AstroFloyd

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.

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

- user2304916

---

你认为将别名返回到Args对于这个目的来说是一个更好的想法吗？https://sphinxcontrib-napoleon.readthedocs.io/en/latest/sphinxcontrib.napoleon.html#sphinxcontrib.napoleon.Config.napoleon_custom_sections - Sibbs Gambling

@SibbsGambling 不行，因为这样额外的值会被合并到现有的参数中。 - moi

Answer 3

你可以配置napoleon来解释Google风格docstring的Returns部分，就像使用napoleon_custom_sections设置来解释Args部分一样。

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

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

- Frank Zalkow

Answer 4

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

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

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

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

- mpariente