Eu já vi alguns estilos diferentes de escrever docstrings em Python, existe um estilo oficial ou "acordado"?
fonte
Eu já vi alguns estilos diferentes de escrever docstrings em Python, existe um estilo oficial ou "acordado"?
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.
Historicamente, um estilo semelhante ao javadoc era predominante; portanto, era usado como base para o Epydoc (com o Epytext
formato 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
"""
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
"""
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
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
"""
É 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.
...
"""Return the squared result"""
ao invés de """Returns the squared result"""
. Embora pessoalmente, escrevo o meu como Tim está aqui, apesar do que o PEP diz.
Aparentemente, ninguém mencionou: você também pode usar o Numpy Docstring Standard . É amplamente utilizado na comunidade científica.
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.
ipython
para testar uma biblioteca, e isso simplifica bastante a leitura dos documentos - tudo o que tenho que digitar é your_module.some_method_im_curious_about?
e recebo todas as impressões legais, incluindo os documentos.
help
função na função / método / classe documentada (e isso poderá ser feito mesmo que você tenha acesso apenas ao módulo compilado). Pessoalmente, acho que devemos ter isso em mente ao escolher a convenção de doutrinas (isto é, a intenção é que ela seja lida como está).
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.
pydocstyle --select=D4 tmp.py
verifica uma variedade de problemas de conteúdo da documentação, incluindo a nomeação de seções.
epydoc
,doxygen
,sphinx
? Alguém tem alguma estatística, é um deles vai substituir os outros, em casos como este, muitas opções podem prejudicar.def foo(self, other):\n\t"""\n\t(blank line)\n\t:param other: \n\t:return:\n\t"""