Форматы

Докстоны Python могут быть записаны в нескольких форматах, как показали другие сообщения. Однако формат docstring по умолчанию Sphinx не упоминался и основан на reStructuredText (reST). Вы можете получить некоторую информацию о основных форматах в , что tuto .

Обратите внимание, что reST рекомендуется PEP 287

Далее следуют основные используемые форматы для docstrings.

- Epytext

Исторически был характерен стиль 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
"""

- reST

В настоящее время, вероятно, более распространенным форматом является 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 имеет свой собственный формат , который часто используется. Это также может быть интерпретировано Сфинксом.

Пример:

"""
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.
"""

Даже больше примеров

- Numpydoc

Обратите внимание, что 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 , чтобы автоматически генерировать docstrings в проект Python, еще не задокументированный, или для преобразования существующих docstrings (может смешивать несколько форматов) из формата в другой.

Примечание. взятые из документации Pyment