1

In Google style Python docstring, one can specify Args, Returns, Raises as follows.

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

I have many functions that, instead of returning stuff, write the results to the disk. I find it often useful to also document what the function will write to disk, e.g., using Writes:, which doesn't seem supported by sphinx.ext.napoleon.

What is the best way of doing so?

Caner
  • 57,267
  • 35
  • 174
  • 180
Sibbs Gambling
  • 19,274
  • 42
  • 103
  • 174

1 Answers1

1

For versions sphinx>=1.8.2, you can have a custom section.

In your conf.py you should add the option napoleon_custom_sections = ('Writes', 'Parameters') (To create an alias with Parameters for instance)

Then you can write your docstring this way:

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))
BlueSheepToken
  • 5,751
  • 3
  • 17
  • 42