documentation - Is there a reST Python docstring field for yields? -

i'm trying use rest-style docstrings, i.e.

def foo(bar):     """a method takes bar      :param bar: bar instance     :type bar: bar 

is there standard way document yields? looked @ http://sphinx-doc.org/domains.html#info-field-lists, a-la question [ using javadoc python documentation ], no luck. i'm imagining like,

    :yields: transformed bars     :yield type: baz 

thanks!

google python style guide says:

fine. use "yields:" rather "returns:" in doc string generator functions.

example taken here:

def example_generator(n):     """generators have ``yields`` section instead of ``returns`` section.      args:       n (int): upper limit of range generate, 0 `n` - 1      yields:       int: next number in range of 0 `n` - 1      examples:       examples should written in doctest format, , should illustrate how       use function.        >>> print [i in example_generator(4)]       [0, 1, 2, 3]      """     in range(n):         yield 

note not official python coding style guide.

if going use yields need utilize sphinxcontrib-napoleon extension adding list of extensions in conf.py:

extensions = ['...', ..., 'sphinxcontrib.napoleon'] 

sphinxcontrib-napoleon recognize yields keyword among others on docstring preprocessing step:

napoleon sphinx extension enables sphinx parse both numpy , google style docstrings - style recommended khan academy.

napoleon pre-processor parses numpy , google style docstrings , converts them restructuredtext before sphinx attempts parse them. happens in intermediate step while sphinx processing documentation, doesn't modify of docstrings in actual source code files.

---

personally, think using returns: pretty ok since generator special case of function.