Qual é o formato padrão de documentação Python? [fechadas]


888

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


6
python.org/dev/peps/pep-0008 há uma seção inteira dedicada a strings de documentação
Mechanical_meat

30
Eu acho que esta questão não foi suficiente claro, porque PEP-257 e PEP-8 estão a estabelecer apenas a base para docstrings, mas como sobre epydoc, doxygen, sphinx? Alguém tem alguma estatística, é um deles vai substituir os outros, em casos como este, muitas opções podem prejudicar.
sorin

1
@sorin, eu também gostaria de saber qual marcação, se houver, é a mais comum. Mas acho que a resposta é que nenhum deles é realmente tão comum: as pessoas tendem a preferir olhar diretamente para o código-fonte do Python, em vez de convertê-lo em html. Portanto, é mais útil apenas ser consistente, mas de uma maneira otimizada para legibilidade humana e sem marcação explícita.
Pool #

3
Autocompletes PyCharm de uma forma bastante interessante, que eu acho que é uma boa implementação das instruções necessárias para executá-lo:def foo(self, other):\n\t"""\n\t(blank line)\n\t:param other: \n\t:return:\n\t"""
Matteo Ferla

1
Qual dessas respostas é a que funciona por padrão com o analisador de documentação do VS Code?
William Entriken

Respostas:


1019

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


10
Devo acrescentar que o reST é o que é usado por padrão no JetBrains PyCharm. Basta digitar aspas triplas após definir seu método e pressionar enter. jetbrains.com/pycharm/help/creating-documentation-comments.html
Felipe Almeida

12
A resposta mais abrangente inclui um senso de história e as melhores práticas atuais. Agora, tudo o que precisamos é de algum senso de movimento da comunidade em direção a um novo formato "melhor" e algum esforço adicional da comunidade para criar ferramentas de migração de todas as outras para a nova, para que possamos realmente desenvolver as melhores práticas.
BobHy

2
yo @daouzli, o link do estilo do Google é 404. Acredito que este esteja correto. Você também pode adicionar o exemplo de estilo do Google esfinge . Ótima resposta btw. EDIT: editei sua resposta sozinho.
voy 07/07

4
boa resposta. Ouso dizer onde você pode alterar o formato padrão de docstring no PyCharm (JetBrains): Configurações -> Ferramentas -> Ferramentas Integradas do Python -> Formato do Docstring. Boa sorte!
Jackssn

4
Estou surpreso que ninguém tenha comentado sobre a primeira linha de texto: atualmente está estritamente correto, mas acho que a maneira preferida é colocá-la na primeira linha logo após as aspas triplas. O PEP 8 e o PEP 257 o fazem em quase todos os seus exemplos. O PEP 287 faz do seu jeito, mas na minha experiência não é tão comum.
Lapinot 14/11

323

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

37
Acho o estilo "assinatura em docstrings" muito redundante e detalhado. Para o Python 3+, as anotações de funções são uma maneira muito mais limpa de fazer isso. Pior ainda se usar tipos pseudo-fortes: Python é muito melhor com a digitação de patos.
Evpok

27
sim, mas pelo menos dá uma dica de que tipo de pato é esperado, e maioria dos desenvolvedores não estão em Python 3 ainda
Anentropic

3
@ Evpok pessoalmente, não gosto de anotações de funções. Para usar classes nelas, talvez seja necessário fazer importações desnecessárias; para usar cadeias nelas, você pode ficar sem espaço horizontal descrevendo-as rapidamente. Até agora, não vi sentido em usá-los para nada.
OdraEncoded

5
@ Nathan, o guia de estilo do Google recomenda comentários descritivos e não declarativos, por exemplo, "Obtém linhas de um Bigtable" em vez de "Buscar linhas de um Bigtable". Assim, alterar "Calcular ..." para "Calcula ..." tornaria o seu exemplo mais consistente com o restante do comentário, ou seja, "Retorna" e "Aumenta".
Gwg

2
nit: Após estilo Google, utilização descritiva, em vez de forma imperativa, ou seja, "Calcula ..." e "Adiciona ..."
sbeliakov

228

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

90
Observe que o PEP-8 diz especificamente que os documentos devem ser escritos como comandos / instruções, em vez de descrições, por exemplo. """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.
Cam Jackson

63
Também não concordo com esse conselho (usando o tempo imperativo) porque ele começa a parecer estranho por mais de uma frase. Além disso, você está descrevendo uma função, não dizendo ao leitor o que fazer.
Mk12

14
Nota: A especificação para os documentos prescritivos e não descritivos realmente aparece no PEP-257 , não no PEP-8. Eu vim de uma tradição de Java, onde descrevia funções, mas finalmente comecei a usar o tempo imperativo quando meu paradigma de programação mudou de orientado a objeto para processual. E quando comecei a usar o pycco para gerar documentação no estilo de programação alfabética , ficou muito claro por que o tempo imperativo foi sugerido. Você deve escolher com base no seu paradigma.
precisa saber é o seguinte

26
O imperativo é um humor gramatical . (Desculpe.)
Denis Drescher

5
@ Mk12 As mensagens de confirmação do Git também devem ser escritas como comandos em vez de descrições. E eles também estão " descrevendo " uma alteração de código ", não dizendo ao leitor o que fazer". Então eu acho que é apenas uma convenção escrever descrições como comandos.
onepiece

58

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

2
Formato NumPy O IMHO ocupa muito espaço vertical, o que é escasso nos monitores widescreen (exceto se você usa um girado em 90 graus, mas acho que a maioria das pessoas não). Portanto, o IMHO Google Format é uma boa opção em termos de legibilidade e recursos.
Semanino

3
Suponho que seja algo subjetivo. Depois de ter uma documentação mais complexa (com seções diferentes, com exemplos, etc., ocupando muito espaço vertical, independentemente do formato), acho o formato numpydoc mais fácil de ler / melhor estruturado.
Joris

2
Pessoalmente, sinto que uma docstring tão longa está melhor localizada na documentação, não no código-fonte, se for tão longa que acaba impedindo a legibilidade do módulo.
Jonathan Hartley

12

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.


8
Mencionar PEP-257 no contexto de "como devo documentar corretamente parâmetros, retornar valores, exceções levantadas etc." é uma Piada - não diz uma única palavra sobre eles (embora um exemplo de código mostre alguns). O IMHO Google Format é uma boa opção em termos de legibilidade e recursos.
Semanino

9

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


22
Eu costumo usar ipythonpara 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.
Thanatos

8
Os usuários de uma biblioteca ou de uma API ou que estão escrevendo um plug - in provavelmente examinam o código e precisam entender o código. Acho comentários muito mais cruciais em Python do que em Java ou C # porque os tipos não são declarados. Ajuda muito se os comentários dão uma idéia de que tipo de patos estão sendo passados ​​e devolvidos. (Caso contrário, você precisa realmente percorrer todo o código e registrar que um determinado parâmetro deve ... ser iterável por aqui ... suportar indexação por lá ... suportar subtração numérica no final ... Ah! É basicamente um int array. Um comentário teria ajudado!)
Jon Coombs

Ah não. Os documentos não são invisíveis e isso é um pouco importante. Você poderá ver a sequência de caracteres se executar a helpfunçã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á).
skyking

7

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.


Mencionar PEP-257 no contexto de "como devo documentar corretamente parâmetros, retornar valores, exceções levantadas etc." é uma Piada - não diz uma única palavra sobre eles (embora um exemplo de código mostre alguns). Formato NumPy O IMHO ocupa muito espaço vertical, o que é escasso nos monitores widescreen (exceto se você usa um girado em 90 graus, mas acho que a maioria das pessoas não). Portanto, o IMHO Google Format é uma boa opção em termos de legibilidade e recursos.
Semanino

1
@ Semanino Estou mencionando o Numpy Docstring Standard no contexto do programa pep257, e não o PEP-257. Esse programa agora é chamado de pydocstyle. O pydocstyle permite que você faça algumas verificações numpydoc, por exemplo, pydocstyle --select=D4 tmp.pyverifica uma variedade de problemas de conteúdo da documentação, incluindo a nomeação de seções.
Finn Årup Nielsen 7/11
Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.