Форматы
Строки документации Python могут быть написаны в нескольких форматах, как показано в других сообщениях. Однако формат строки документа Sphinx по умолчанию не был упомянут и основан на reStructuredText (reST) . Вы можете получить информацию об основных форматах в этом посте .
Обратите внимание, что ПКП 287 рекомендует reST
Ниже приведены основные используемые форматы для строк документации.
- эпитекст
Исторически стиль, похожий на javadoc, был распространен, поэтому он использовался в качестве основы для Epydoc (с так называемым Epytext
форматом) для создания документации.
Пример:
"""
This is a javadoc style.
@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""
- остаток
В настоящее время, вероятно, более распространенным форматом является формат reStructuredText (reST), который используется Sphinx для создания документации. Примечание: он используется по умолчанию в JetBrains PyCharm (введите тройные кавычки после определения метода и нажмите Enter). Он также используется по умолчанию в качестве выходного формата в Pyment.
Пример:
"""
This is a reST style.
:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""
- Google
У Google есть собственный формат, который часто используется. Это также может быть интерпретировано Сфинксом (то есть с использованием плагина Napoleon ).
Пример:
"""
This is an example of Google style.
Args:
param1: This is the first param.
param2: This is a second param.
Returns:
This is a description of what is returned.
Raises:
KeyError: Raises an exception.
"""
Еще больше примеров
- Нумпидок
Обратите внимание, что Numpy рекомендует следовать своему собственному numpydoc на основе формата Google и может использоваться Sphinx.
"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.
Parameters
----------
first : array_like
the 1st param name `first`
second :
the 2nd param
third : {'value', 'other'}, optional
the 3rd param, by default 'value'
Returns
-------
string
a value in a string
Raises
------
KeyError
when a key error
OtherError
when an other error
"""
Преобразование / Генерация
Можно использовать инструмент, такой как Pyment, для автоматической генерации строк документации в проект Python, еще не документированный, или для преобразования существующих строк документации (можно смешивать несколько форматов) из формата в другой.
Примечание: примеры взяты из документации Pyment