it-swarm.com.ru

Каков стандартный формат Python документа?

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

750
Noah McIlraith

Форматы

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

Обратите внимание, что reST рекомендуется PEP 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

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

Четный больше примеров

- Нумпидок

Обратите внимание, что 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

825
daouzli

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

Соглашения о документации представлены в 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. 
    ...
222
Tim McNamara

Как очевидно, никто не упомянул об этом: вы также можете использовать 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
48
joris

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

11
bstpierre

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

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

5
Finn Årup Nielsen

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

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

4
Colonel Panic

Официальные стили Python перечислены в PEP-8 .

0
Amber