是否有用于收益的 Sphinx reST Python 文档字符串字段？

Question

I'm trying to use reST-style docstrings, ie

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 1

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()

And after Python 3, use https://pypi.python.org/pypi/sphinx-autodoc-annotation with syntax:

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

Answer 2

I have reviewed the other answer and it doesn't in my opinion answer the question.

The way to document a generator, although not the best, is by using :return as in the rest of the docs. Use the description to give notice that it is a generator.

Yields from Google/Numpy style docs convert yields to return clauses.

https://bitbucket.org/RobRuana/sphinx-contrib/src/a06ae33f1c70322c271a97133169d96a5ce1a6c2/napoleon/sphinxcontrib/napoleon/docstring.py?at=default&fileviewer=file-view-default#docstring.py-678:680