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