Что такое стандартный формат документации Python?
Я видел несколько разных стилей написания строк документации на Python, есть ли официальный или "согласованный" стиль?
8 ответов
Форматы
Строки документации Python могут быть написаны в нескольких форматах, как показано в других сообщениях. Однако формат строки документа Sphinx по умолчанию не был упомянут и основан на reStructuredText (reST). Вы можете получить информацию об основных форматах в этом туто.
Обратите внимание, что ПКП 287 рекомендует РЕСТ
Ниже приведены основные используемые форматы для строк документации.
- эпитекст
Исторически сложился стиль, похожий на 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 есть собственный формат, который часто используется. Это также может быть интерпретировано Сфинксом (т.е. с использованием плагина 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
Руководство по стилю Google содержит отличное руководство по стилю Python. Он включает в себя соглашения для удобочитаемого синтаксиса документации, который предлагает лучшее руководство, чем PEP-257. Например:
def square_root(n):
"""Calculate the square root of a number.
Args:
n: the number to get the square root of.
Returns:
the square root of n.
Raises:
TypeError: if n is not a number.
ValueError: if n is negative.
"""
pass
Мне нравится расширять это, чтобы также включить информацию о типе в аргументы, как описано в этом руководстве по документации Sphinx. Например:
def add_value(self, value):
"""Add a new value.
Args:
value (str): the value to add.
"""
pass
Соглашения о документах содержатся в PEP-257 с гораздо более подробной информацией, чем в PEP-8.
Тем не менее, строки документации кажутся гораздо более личными, чем другие области кода. У разных проектов будет свой стандарт.
Я склонен всегда включать строки документов, потому что они демонстрируют, как использовать функцию и что она делает очень быстро.
Я предпочитаю, чтобы все было согласованно, независимо от длины строки. Мне нравится, как кодировать выглядит, когда отступы и интервалы согласованы. Это означает, что я использую:
def sq(n):
"""
Return the square of n.
"""
return n * n
Над:
def sq(n):
"""Returns the square of n."""
return n * n
И, как правило, не комментируйте первую строку в длинных строках документации:
def sq(n):
"""
Return the square of n, accepting all numeric types:
>>> sq(10)
100
>>> sq(10.434)
108.86835599999999
Raises a TypeError when input is invalid:
>>> sq(4*'435')
Traceback (most recent call last):
...
TypeError: can't multiply sequence by non-int of type 'str'
"""
return n*n
То есть, я считаю, что строки документации, которые начинаются таким образом, являются грязными.
def sq(n):
"""Return the squared result.
...
Как очевидно, никто не упомянул об этом: вы также можете использовать Numpy Docstring Standard. Широко используется в научном сообществе.
- Спецификация формата от NumPy вместе с примером
- У вас есть расширение сфинкса для его рендеринга: numpydoc
- И пример того, как красиво может выглядеть визуализированная строка документа: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html
Расширение наполеоновских сфинксов для анализа строк документов в стиле Google (рекомендуется в ответе @Nathan) также поддерживает строку документов в стиле Numpy и дает краткое сравнение обоих.
И последний базовый пример, чтобы дать представление о том, как это выглядит:
def func(arg1, arg2):
"""Summary line.
Extended description of function.
Parameters
----------
arg1 : int
Description of arg1
arg2 : str
Description of arg2
Returns
-------
bool
Description of return value
See Also
--------
otherfunc : some related other function
Examples
--------
These are written in doctest format, and should illustrate how to
use the function.
>>> a=[1,2,3]
>>> print [x + 3 for x in a]
[4, 5, 6]
"""
return True
Это Питон; все идет. Подумайте, как опубликовать вашу документацию. Строки документов невидимы, кроме читателей вашего исходного кода.
Людям очень нравится просматривать и искать документацию в Интернете. Для этого используйте инструмент документации Sphinx. Это де-факто стандарт для документирования проектов Python. Продукт красивый - взгляните на https://python-guide.readthedocs.org/en/latest/. Сайт Read the Docs будет размещать ваши документы бесплатно.
Я предлагаю использовать Python-программу Владимира Келешева pep257 для проверки ваших строк документации на соответствие PEP-257 и Numpy Docstring Standard для описания параметров, возвратов и т. Д.
pep257 сообщит о расхождении, которое вы производите от стандарта, и называется pylint и pep8.