Есть ли поле 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 

Благодаря!

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 конвертируют доходность в возвращаемые предложения.

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

  • Сфинкс, лучшие практики
  • Названия разделов Sphinx apidoc для имен модулей / пакетов Python
  • sphinx autodoc включают подфункции
  • Автоматизированный способ переключения с форматирования docstring epydoc на форматирование dhstnx sphinx?
  • Python: Как я могу определить в sphinx, какие файлы .rst и каталоги должны использоваться?
  • Программа командной строки Python: создание man-страницы из существующей документации и включение в дистрибутив
  • Как добавить ссылку «предыдущая глава» и «следующая глава» в документации, созданной Sphinx?
  • Добавление тега скрипта javascript в какое-то место, чтобы он работал для каждого файла в документации sphinx
  • Python - лучший язык программирования в мире.