Есть ли поле doststring reST Python для уроков?
Я пытаюсь использовать 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 ], но не повезло. Я представляю что-то вроде,
- Python Sphinx ссылается на длинные имена
- Как создать документацию на основе Sphinx в проекте Jython?
- можете ли вы переименовать «оглавление» в боковую панель sphinx?
- Перестановка переменных Sphinx в кодовых блоках
- Можно ли скрыть аргументы функции Python в Sphinx?
:yields: transformed bars :yield type: Baz
Благодаря!
3 Solutions collect form web for “Есть ли поле doststring reST Python для уроков?”
Google python style guide говорится:
Хорошо. Используйте «Уроки:», а не «Возвраты:» в строке документа для функций генератора.
Пример, взятый здесь :
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:
Napoleon – это расширение Sphinx, которое позволяет Sphinx анализировать как цифровые, так и догстеры стиля Google – стиль, рекомендованный Академией Хан.
Наполеон является предварительным процессором, который анализирует docstrings NumPy и Google и преобразует их в reStructuredText, прежде чем Sphinx попытается их проанализировать. Это происходит на промежуточном этапе, в то время как Sphinx обрабатывает документацию, поэтому он не изменяет никаких докстронтов в ваших файлах исходного кода.
Лично я думаю, что использование Returns: довольно хорошо, потому что generator – это в основном частный случай function .
Перед написанием Python 3 + аннотации:
from typing import List def f(): """ :rtype: Generator[:class:`SomeClass`] """ yield SomeClass()
После https://pypi.python.org/pypi/sphinx-autodoc-annotation :
from typing import Iterator def f() -> Iterator[SomeClass]: yield SomeClass()
Я рассмотрел другой ответ, и это, на мой взгляд, не отвечает на вопрос.
Способ документирования генератора, хотя и не самый лучший, заключается в использовании :return как и в остальных документах. Используйте описание, чтобы заметить, что это генератор.
Доходы от документов стиля Google / Numpy конвертируют доходность в возвращаемые предложения.