Я пытаюсь использовать docstrings типа reST, т.е.
def foo(bar):
"""a method that takes a bar
:param bar: a Bar instance
:type bar: Bar
Есть ли стандартный способ документировать yields? Я посмотрел на http://sphinx-doc.org/domains.html#info-field-lists, a-la this question [Использование javadoc для документации Python], но не повезло. Я представляю что-то вроде:
:yields: transformed bars
:yield type: Baz
Спасибо!
итератора []
Аннотации Python 3 предлагают стандартизованный синтаксис Iterator[] для этого, как описано в: https://docs.python.org/3/library/typing.html#typing.Generator
Перед Python 3 я рекомендую использовать этот синтаксис, чтобы упростить его перенос позже:
from typing import List
def f():
"""
:rtype: Iterator[:class:`SomeClass`]
"""
yield SomeClass()
И после Python 3 используйте https://pypi.python.org/pypi/sphinx-autodoc-annotation с синтаксисом:
from typing import Iterator
def f() -> Iterator[SomeClass]:
yield SomeClass()
Google python style guide говорит:
Fine. Используйте "Доходность", а не "Возвраты:" в строке документа для функции генератора.
Пример из здесь:
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
Обратите внимание, что это не официальный стиль руководства по кодированию питона.
Если вы собираетесь использовать Yields, вам нужно использовать расширение sphinxcontrib-napoleon, добавив его в список extensions в conf.py:
extensions = ['...', ..., 'sphinxcontrib.napoleon']
sphinxcontrib-napoleon распознать Yields ключевое слово среди других на этапе предварительной обработки docstring:
Наполеон - это расширение Сфинкса, которое позволяет Sphinx анализировать как NumPy и docstrings в стиле Google - стиль, рекомендованный Академией Хан.
Napoleon - это предварительный процессор, который анализирует NumPy и стиль Google docstrings и преобразует их в reStructuredText до Sphinx попытки разобрать их. Это происходит на промежуточном этапе, пока Sphinx обрабатывает документацию, поэтому он не модифицирует ни одну из docstrings в ваших файлах исходного кода.
Лично я думаю, что использование Returns: довольно хорошо, так как generator - это в основном частный случай function.
Я рассмотрел другой ответ, и он, на мой взгляд, не отвечает на вопрос.
Способ документирования генератора, хотя и не самый лучший, заключается в использовании :return, как и в остальных документах. Используйте описание, чтобы заметить, что это генератор.
Уступки из документов стиля Google/Numpy конвертируют доходность в возвращаемые предложения.