Gibt es ein Sphinx reST Python Docstring-Feld für Erträge?

Question

Ich versuche reST-Stil Docstrings, das heißt

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

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

Gibt es einen Standard zu dokumentieren yields zu bedienen? Ich schaute auf http://sphinx-doc.org/domains.html#info-field-lists, a-la diese Frage [Using javadoc for Python documentation], aber kein Glück. Ich stelle mir sowas vor,

:yields: transformed bars 
    :yield type: Baz 

Danke!

Answer 1

Google python style guide sagt:

Fein. Verwenden Sie "Yields:" statt "Returns:" in der Doc-Zeichenfolge für Generatorfunktionen.

Beispiel aus here genommen:

def example_generator(n): 
    """Generators have a ``Yields`` section instead of a ``Returns`` section. 

    Args: 
     n (int): The upper limit of the range to generate, from 0 to `n` - 1 

    Yields: 
     int: The next number in the range of 0 to `n` - 1 

    Examples: 
     Examples should be written in doctest format, and should illustrate how 
     to use the function. 

     >>> print [i for i in example_generator(4)] 
     [0, 1, 2, 3] 

    """ 
    for i in range(n): 
     yield i 

Beachten Sie, dass diese Codierung Styleguide keine offizielle Python ist.

Wenn Sie Yields Sie sphinxcontrib-napoleon Erweiterung zu nutzen, müssen verwenden werden, indem es auf die Liste der extensions in conf.py fügte hinzu:

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

sphinxcontrib-napoleon erkennen Yields Stichwort among others auf der docstring Vorverarbeitungsschritt:

Napoleon ist eine Sphinx-Erweiterung, mit der Sphinx sowohl NumPy als auch Google-Style-Dokument analysieren kann Saiten - der von der Khan Academy empfohlene Stil.

Napoleon ist ein Pre-Prozessor, der NumPy und im Google-Stil Docstrings und wandelt sie parst reStructuredText vor Sphinx sie zu analysieren versucht. Dies geschieht in einem Zwischenschritt, während Sphinx die Dokumentation verarbeitet, also ändert es nichts von die Docstrings in Ihren tatsächlichen Quellcodedateien.

---

Ich persönlich denke, Returns: mit ziemlich ok ist, da ein generator im Grunde ein Spezialfall eines function ist.

Answer 2

Ich habe die andere Antwort überprüft und es beantwortet meiner Meinung nach nicht die Frage.

Die Dokumentation eines Generators, obwohl nicht der beste, ist mit :return wie im Rest der Dokumentation. Verwenden Sie die Beschreibung, um anzuzeigen, dass es sich um einen Generator handelt.

Bei Erträgen aus Google/Numpy-Stildokumenten werden Erträge in Rückgabeklauseln konvertiert.

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

Answer 3

Iterator []

Python 3 Anmerkungen bieten eine standardisierte Iterator[] Syntax für diese wie dokumentiert: https://docs.python.org/3/library/typing.html#typing.Generator

Vor Python 3, empfehle ich, dass Sie diese Syntax verwenden zu machen es ist einfacher, später zu portieren:

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

Und nach Python 3 verwenden https://pypi.python.org/pypi/sphinx-autodoc-annotation mit Syntax:

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