Что такое стандартный формат документации Python? [закрыто]


889

Я видел несколько разных стилей написания строк документации на Python, есть ли официальный или "согласованный" стиль?


6
python.org/dev/peps/pep-0008 есть целый раздел, посвященный строкам документации
mechanical_meat

30
Я думаю , что этот вопрос был недостаточно ясен , так как PEP-257 и PEP-8 являются создание только базы для строк документации, но как насчет epydoc, doxygen, sphinx? Есть ли у кого-нибудь статистика, один из них собирается заменить другие, в таких случаях слишком много вариантов может повредить.
сорин

1
@ Сорин, я также хотел бы знать, какая разметка, если таковая имеется, является наиболее распространенной. Но я думаю, что ответ заключается в том, что ни один из них на самом деле не настолько распространен: люди предпочитают смотреть непосредственно на исходный код Python, а не преобразовывать его в html. Таким образом, наиболее полезно просто быть последовательным, но таким образом, который оптимизирован для удобства чтения человеком, без явной разметки.
пул

3
PyCharm выполняет автозаполнение довольно интересным способом, который, я думаю, является хорошей реализацией инструкций, необходимых для его запуска:def foo(self, other):\n\t"""\n\t(blank line)\n\t:param other: \n\t:return:\n\t"""
Matteo Ferla

1
Какой из этих ответов по умолчанию работает с анализатором документации VS Code?
Уильям Энтрикен

Ответы:


1019

Форматы

Строки документации 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


10
Я мог бы добавить, что reST - это то, что используется по умолчанию в JetBrains PyCharm. Просто введите тройные кавычки после определения вашего метода и нажмите Enter. jetbrains.com/pycharm/help/creating-documentation-comments.html
Фелипе Алмейда

12
Наиболее полный ответ, включает в себя чувство истории и современные лучшие практики. Теперь все, что нам нужно, это чувство движения сообщества к новому «лучшему» формату и некоторые дополнительные усилия сообщества по созданию инструментов миграции из всех остальных в новый, чтобы мы могли на самом деле развивать лучшие практики.
BobHy

2
yo @daouzli, ссылка в стиле Google 404. Я считаю, что это правильно. Вы можете добавить sphinx google style example . Отличный ответ, кстати. РЕДАКТИРОВАТЬ: я отредактировал ваш ответ самостоятельно.
Вой

4
хороший ответ Смею сказать, где вы можете изменить формат строки документа по умолчанию в PyCharm (JetBrains): Настройки -> Инструменты -> Python Integrated Tools -> Формат строки документа. Удачи!
Jackssn

4
Я удивлен, что никто не прокомментировал первую текстовую строку: в настоящее время это строго говоря правильно, но я чувствую, что предпочтительным способом является поместить его в первую строку сразу после тройных кавычек. PEP 8 и PEP 257 делают это почти во всех своих примерах. PEP 287 делает это по-своему, но по моему опыту это не так часто.
Lapinot

323

Руководство по стилю 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

37
Я нахожу стиль «подпись в документах» ужасно избыточным и многословным. Для Python 3+ аннотации функций - намного более чистый способ сделать это. Еще хуже, если он использует псевдо-сильные типы: Python намного лучше с типизацией утиной.
Евпок

27
да, но, по крайней мере, это дает намек на то, какого типа утка ожидается, и большинство разработчиков еще не на Python 3
Anentropic

3
@ Евпок лично, мне не нравятся функциональные аннотации. Чтобы использовать классы в них, вам, возможно, придется выполнять ненужные операции импорта, чтобы использовать строки в них, вы можете очень быстро исчерпать горизонтальное пространство, описывая их. До сих пор я не видел смысла использовать их для чего-либо.
OdraEncoded

5
@Nathan, руководство по стилю Google рекомендует комментарии, которые являются описательными, а не декларативными, например, «Извлекает строки из большой таблицы» вместо «Извлекает строки из большой таблицы». Таким образом, изменение «Рассчитать ...» на «Рассчитывает ...» сделает ваш пример более совместимым с остальной частью комментария, то есть «Возвраты» и «Повышения».
GWG

2
nit: Следуя стилю Google, используйте описательную, а не императивную форму, то есть «Вычисляет ...» и «Добавляет ...»
sbeliakov

228

Соглашения о документах содержатся в 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. 
    ...

90
Обратите внимание, что PEP-8, в частности, говорит, что строки документации должны быть написаны как команды / инструкции, а не описания, например. """Return the squared result"""а не """Returns the squared result""". Хотя лично я пишу свои, как Тим, как здесь, несмотря на то, что говорит PEP.
Кэм Джексон

63
Я также не согласен с этим советом (используя императивное время), потому что он начинает звучать неловко для всего, что длиннее одного предложения. Кроме того, вы описываете функцию, а не говорите читателю, что делать.
mk12

14
Примечание. Спецификация предписывающих, а не описательных строк документации фактически появляется в PEP-257 , а не в PEP-8. Я пришел из традиции Java, где я описывал функции, но в конце концов я начал использовать императивное время, когда моя парадигма программирования переключилась с объектно-ориентированной на процедурную. И когда я начал использовать pycco для генерации документации в стиле грамотного программирования, стало ясно, почему было предложено императивное время. Вы должны выбрать на основе вашей парадигмы.
karan.dodia

26
Императивом является грамматическое настроение . (Извините.)
Денис Дрешер

5
@ Mk12 Сообщения Git commit также должны быть записаны как команды, а не как описания. И они также « описывают » изменение кода, «не говоря читателю, что делать». Поэтому я думаю, что просто писать описания в виде команд.
oneple

58

Как очевидно, никто не упомянул об этом: вы также можете использовать Numpy Docstring Standard . Широко используется в научном сообществе.

Расширение наполеоновских сфинксов для анализа строк документов в стиле 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

2
Формат NumPy IMHO занимает слишком много вертикального пространства, которого недостаточно на широкоэкранных мониторах (за исключением того, что вы используете один, повернутый на 90 градусов, но я полагаю, что большинство людей этого не делают). Итак, IMHO Google Format является хорошим выбором с точки зрения читаемости и функций.
Семанино,

3
Я полагаю, это несколько субъективно. Если у вас есть более сложная строка документации (с разными разделами, с примерами и т. Д., Так что в любом случае занимает много вертикального пространства независимо от формата), я считаю, что формат numpydoc легче читать / лучше структурировать.
Йорис

2
Лично я чувствую, что такая длинная строка документации лучше расположена в документации, а не в исходном коде, если она слишком длинная, это мешает удобочитаемости модуля.
Джонатан Хартли

12

PEP-8 является официальным стандартом кодирования Python. Он содержит раздел о строках документации, который ссылается на PEP-257 - полную спецификацию для строк документации.


8
Упоминание PEP-257 в контексте «как правильно задокументировать параметры, возвращаемые значения, возникшие исключения и т. Д.» - это ШУТКА - в нем не сказано ни одного слова (хотя пример кода показывает некоторые из них). IMHO Google Format - хороший выбор с точки зрения читабельности и возможностей.
Семанино

9

Это Питон; все идет . Подумайте, как опубликовать вашу документацию . Строки документов невидимы, кроме читателей вашего исходного кода.

Людям очень нравится просматривать и искать документацию в Интернете. Для этого используйте инструмент документации Sphinx . Это де-факто стандарт для документирования проектов Python. Продукт красивый - взгляните на https://python-guide.readthedocs.org/en/latest/ . Сайт Read the Docs будет размещать ваши документы бесплатно.


22
Я обычно использую ipythonдля тест-драйва библиотеку, и это упрощает чтение строк документации - все, что мне нужно набрать, - your_module.some_method_im_curious_about?и я получаю все хорошие распечатки, включая строку документации.
Танатос

8
Пользователи библиотеки или API или те, кто пишет плагин , скорее всего, взглянут на код и должны в нем разобраться. Я нахожу комментарии гораздо более важными в Python, чем в Java или C #, потому что типы не объявлены. Очень помогает, если комментарии дают представление о том, какие утки передаются и возвращаются. (В противном случае вам нужно на самом деле пройти весь код и подсчитать, что данный параметр должен быть ... итеративным здесь ... поддерживать индексирование там ... поддерживать числовое вычитание в конце ... Ага! Это в основном int массив. Комментарий помог бы!)
Джон Кумбс

Эх, нет Строки документов не являются невидимыми, и это немного. Вы можете увидеть строку документации, если запустите helpфункцию в документированной функции / методе / классе (и это можно сделать, даже если у вас есть доступ только к скомпилированному модулю). Лично я думаю, что следует помнить об этом при выборе соглашения docstring (то есть, что он предназначен для чтения как есть).
скайкинг

7

Я предлагаю использовать Python-программу Владимира Келешева pep257, чтобы проверить ваши строки документов на соответствие PEP-257 и Numpy Docstring Standard для описания параметров, возвратов и т. Д.

pep257 сообщит о расхождении, которое вы производите от стандарта, и называется pylint и pep8.


Упоминание PEP-257 в контексте «как правильно задокументировать параметры, возвращаемые значения, возникшие исключения и т. Д.» - это ШУТКА - в нем не сказано ни одного слова (хотя пример кода показывает некоторые из них). Формат NumPy IMHO занимает слишком много вертикального пространства, которого недостаточно на широкоэкранных мониторах (за исключением того, что вы используете один, повернутый на 90 градусов, но я полагаю, что большинство людей этого не делают). Итак, IMHO Google Format является хорошим выбором с точки зрения читаемости и функций.
Семанино,

1
@ Semanino Я упоминаю стандарт Numpy Docstring в контексте программы pep257, а не PEP-257. Эта программа теперь называется pydocstyle. pydocstyle позволяет вам выполнять некоторые проверки numpydoc, например, pydocstyle --select=D4 tmp.pyпроверки ряда проблем с содержимым документации, включая именование разделов.
Финн Оруп Нильсен
Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.