Eu já vi alguns estilos diferentes de escrever docstrings em Python, existe um estilo oficial ou "acordado"?

Formatos

As documentações em Python podem ser escritas seguindo vários formatos, como as outras postagens mostraram. No entanto, o formato padrão de documentação do Sphinx não foi mencionado e é baseado em reStructuredText (reST) . Você pode obter algumas informações sobre os principais formatos nesta postagem do blog .

Observe que o reST é recomendado pelo PEP 287

A seguir, os principais formatos usados ​​para documentos.

- Epytext

Historicamente, um estilo semelhante ao javadoc era predominante; portanto, era usado como base para o Epydoc (com o Epytextformato chamado ) gerar documentação.

Exemplo:

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

- descansar

Atualmente, o formato provavelmente mais prevalente é o formato reStructuredText (reST) usado pelo Sphinx para gerar documentação. Nota: é usado por padrão no JetBrains PyCharm (digite aspas triplas após definir um método e pressione enter). Também é usado por padrão como formato de saída no Pyment.

Exemplo:

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

O Google tem seu próprio formato, que é frequentemente usado. Também pode ser interpretado pelo Sphinx (por exemplo, usando o plugin Napoleon ).

Exemplo:

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

Ainda mais exemplos

- Numpydoc

Observe que a Numpy recomenda seguir seu próprio numpydoc com base no formato do Google e utilizável pela 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
"""

Convertendo / Gerando

É possível usar uma ferramenta como Pyment para gerar automaticamente docstrings em um projeto Python ainda não documentado, ou converter documentos existentes (podem estar misturando vários formatos) de um formato para outro.

Nota: Os exemplos são retirados da documentação do Pyment

O guia de estilo do Google contém um excelente guia de estilo Python. Inclui convenções para a sintaxe legível da documentação que oferece melhores orientações que o PEP-257. Por exemplo:

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

Eu gostaria de estender isso para incluir também informações de tipo nos argumentos, conforme descrito neste tutorial de documentação do Sphinx . Por exemplo:

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

As convenções de documentação estão no PEP-257 com muito mais detalhes que o PEP-8.

No entanto, as doutrinas parecem ser muito mais pessoais do que outras áreas do código. Projetos diferentes terão seu próprio padrão.

Costumo sempre incluir doutrinas, porque elas demonstram como usar a função e o que ela faz muito rapidamente.

Prefiro manter as coisas consistentes, independentemente do comprimento da string. Eu gosto de codificar a aparência quando o recuo e o espaçamento são consistentes. Isso significa que eu uso:

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

Sobre:

def sq(n):
    """Returns the square of n."""
    return n * n

E tendem a deixar de comentar a primeira linha em documentos mais longos:

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

Ou seja, acho que as doutrinas que começam assim são confusas.

def sq(n):
    """Return the squared result. 
    ...

Aparentemente, ninguém mencionou: você também pode usar o Numpy Docstring Standard . É amplamente utilizado na comunidade científica.

• A especificação do formato de numpy junto com um exemplo
• Você tem uma extensão de esfinge para renderizá-la: numpydoc
• E um exemplo de quão bonita pode ser uma docstring renderizada: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

A extensão da esfinge napoleana para analisar as doutrinas no estilo do Google (recomendada na resposta de @Nathan) também suporta as doutrinas no estilo Numpy e faz uma breve comparação de ambas.

E por último, um exemplo básico para dar uma idéia de como é:

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

O PEP-8 é o padrão oficial de codificação python. Ele contém uma seção sobre documentos, que se refere ao PEP-257 - uma especificação completa para documentos.

É Python; vale tudo . Considere como publicar sua documentação . As strings de documentos são invisíveis, exceto para os leitores do seu código-fonte.

As pessoas realmente gostam de navegar e pesquisar documentação na web. Para conseguir isso, use a ferramenta de documentação Sphinx . É o padrão de fato para documentar projetos Python. O produto é bonito - dê uma olhada em https://python-guide.readthedocs.org/en/latest/ . O site Read the Docs hospedará seus documentos gratuitamente.

Sugiro usar o programa pep257 Python de Vladimir Keleshev para verificar seus documentos em relação ao PEP-257 e ao Numpy Docstring Standard para descrever parâmetros, retornos etc.

pep257 relatará divergências que você faz do padrão e é chamado de pylint e pep8.