在Google风格的Python文档字符串中“写”？

Question

在Google风格的Python文档字符串中，可以指定Args，Returns，Raises如下。

"""This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyErr
"""

我有许多函数，而不是返回的东西，将结果写入磁盘。我发现通常也可以记录函数写入磁盘的内容，例如，使用Writes:似乎不支持的sphinx.ext.napoleon。

这样做的最佳方法是什么？

Answer 1

对于版本sphinx>=1.8.2，你可以有一个custom section。

在您的conf.py中，您应该添加选项napoleon_custom_sections = ('Writes', 'Parameters')（例如，创建带参数的别名）

然后你可以这样写你的文档字符串：

from sphinxcontrib.napoleon import Config
from sphinxcontrib.napoleon import GoogleDocstring

config = Config(napoleon_use_param=True, napoleon_use_rtype=True, napoleon_custom_sections=('Writes', 'Parameters'))
docstring="""This is an example of Google style with a custom section.

Args:
    param1: This is the first param.
    param2: This is a second parpytham.

Returns:
    This is a description of what is returned.

Raises:
    KeyErr

Writes:
    write1: This is writting things !

"""

print(GoogleDocstring(docstring, config))