Is there a Sphinx reST Python docstring field for yields?

python python-sphinx restructuredtext

gatoatigrado · Jun 28, 2014 · Viewed 7.2k times · Source

I'm trying to use reST-style docstrings, i.e.

def foo(bar):
    """a method that takes a bar

    :param bar: a Bar instance
    :type bar: Bar

Is there a standard way to document yields? I looked at http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists, a-la this question [ Using javadoc for Python documentation ], but no luck. I'm imagining something like,

:yields: transformed bars
:yield type: Baz

Thanks!

Answer

Python 3.5 Iterator[] annotation

They offer a standardized Iterator[] syntax for this as documented at: https://docs.python.org/3/library/typing.html#typing.Generator

Before Python 3, I recommend that you use this syntax to make it easier to port later on:

from typing import List
def f():
    """
    :rtype: Iterator[:class:`SomeClass`]
    """
    yield SomeClass()

from typing import Iterator
def f() -> Iterator[SomeClass]:
    yield SomeClass()