Есть ли поле 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 ], но не повезло. Я представляю что-то вроде,
:yields: transformed bars :yield type: Baz
Благодаря!
- Как получить документацию Python Sphinx в формате только для данных?
- Замены внутри ссылок в reST / Sphinx
- Можно ли разместить разделы внутри контейнера в reStructuredText?
- Рабочий процесс Sphinx и JavaScript
- Создание большой таблицы сначала с вложенными заголовками столбцов и получение рендеринга латекса для обертывания текста заголовка
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 конвертируют доходность в возвращаемые предложения.
- Как документировать константу модуля в Python?
- Не удается заставить sphinx ссылаться под toctree на другой документ
- Литерал «*» в RestructuredText
- Многострочное описание описания параметра в docstring python
- Пользовательские директивы в Sphinx
- Как добавить теги стиля блога в reStructuredText с Sphinx
- Сетка изображения в reStructuredText / Sphinx
- Предотвращение вложенности секций в Python Sphinx при использовании toctree
- Якорь Python Sphinx на произвольной строке