Есть ли поле docstring sphinx reST Python docstring для уроков?

Я пытаюсь использовать 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

Спасибо!

Ответы

Ответ 1

итератора []

Аннотации 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()

Ответ 2

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.

Ответ 3

Я рассмотрел другой ответ, и он, на мой взгляд, не отвечает на вопрос.

Способ документирования генератора, хотя и не самый лучший, заключается в использовании :return, как и в остальных документах. Используйте описание, чтобы заметить, что это генератор.

Уступки из документов стиля Google/Numpy конвертируют доходность в возвращаемые предложения.

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