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

Форматы

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

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

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

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

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

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

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