谷歌风格的 Python 文档字符串"Writes"？

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 ，您可以有一个自定义部分。

在您的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))