«Пишет» в гугл стиле Python docstring?

Question

В строке документации Python в стиле Google можно указать 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))