谷歌风格的Python docstring中的“Writes”？

Question

在Google风格的Python docstring中，可以指定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:，这似乎不受{}的支持。在

最好的办法是什么？在

Answer 1

对于版本sphinx>=1.8.2，可以使用custom section。在

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

然后您可以这样编写docstring：

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))