Como documentar o código Python com doxygen [fechado]

Eu gosto do doxygen para criar documentação de código C ou PHP. Tenho um próximo projeto Python e acho que me lembro que Python não tem /* .. */comentários e também tem seu próprio recurso de autodocumentação, o que parece ser a maneira python de documentar.

Já que estou familiarizado com o doxygen, como posso usá-lo para produzir minha documentação Python? Há algo em particular que eu preciso estar ciente?

Isso está documentado no site doxygen , mas para resumir aqui:

Você pode usar doxygen para documentar seu código Python. Você pode usar a sintaxe de string de documentação do Python:

"""@package docstring
Documentation for this module.

More details.
"""

def func():
    """Documentation for a function.

    More details.
    """
    pass

Nesse caso, os comentários serão extraídos pelo doxygen, mas você não poderá usar nenhum dos comandos especiais do doxygen .

Ou você pode (semelhante às linguagens de estilo C em doxygen) dobrar o marcador de comentário ( #) na primeira linha antes do membro:

## @package pyexample
#  Documentation for this module.
#
#  More details.

## Documentation for a function.
#
#  More details.
def func():
    pass

Nesse caso, você pode usar os comandos especiais doxygen. Não há um modo de saída Python específico, mas aparentemente você pode melhorar os resultados definindo OPTMIZE_OUTPUT_JAVAcomo YES.

Honestamente, estou um pouco surpreso com a diferença - parece que uma vez que o doxygen pode detectar os comentários nos blocos ## ou "" ", a maior parte do trabalho estaria feito e você seria capaz de usar os comandos especiais em Em qualquer caso. Talvez eles esperem que as pessoas que usam "" "adiram a mais práticas de documentação Pythônica e isso iria interferir com os comandos especiais doxygen?

O filtro de entrada doxypy permite que você use praticamente todas as tags de formatação do Doxygen em um formato docstring padrão do Python. Eu o uso para documentar uma grande estrutura mista de aplicativo de jogos C ++ e Python, e está funcionando bem.

No final, você só tem duas opções:

Você gera seu conteúdo usando Doxygen ou você gera seu conteúdo usando Sphinx *.

1. Doxygen : Não é a ferramenta preferida para a maioria dos projetos Python. Mas se você tiver que lidar com outros projetos relacionados escritos em C ou C ++, pode fazer sentido. Para isso, você pode melhorar a integração entre Doxygen e Python usando doxypypy .

2. Sphinx : A ferramenta de fato para documentar um projeto Python. Você tem três opções aqui: manual, semiautomático (geração de stub) e totalmente automático (semelhante ao Doxygen).

   1. Para documentação de API manual, você tem o Sphinx autodoc . Isso é ótimo para escrever um guia do usuário com elementos gerados por API incorporados.
   2. Para semi-automático, você tem o resumo automático Sphinx . Você pode configurar seu sistema de compilação para chamar sphinx-autogen ou configurar seu Sphinx com a autosummary_generateconfiguração. Você precisará configurar uma página com os resumos automáticos e, em seguida, editar as páginas manualmente. Você tem opções, mas minha experiência com essa abordagem é que ela exige muita configuração e, no final, mesmo depois de criar novos modelos, encontrei bugs e a impossibilidade de determinar exatamente o que foi exposto como API pública e o que não. Minha opinião é que esta ferramenta é boa para geração de stub que exigirá edição manual e nada mais. É como um atalho para acabar no manual.
   3. Totalmente automatizado. Isso foi criticado muitas vezes e por muito tempo não tínhamos um bom gerador de API Python totalmente automático integrado ao Sphinx até o surgimento do AutoAPI , que é uma novidade no bloco. Este é de longe o melhor para a geração automática de API em Python (nota: autopromoção sem vergonha).

Existem outras opções a serem observadas:

• Respire : começou como uma ideia muito boa e faz sentido quando você trabalha com vários projetos relacionados em outras linguagens que usam Doxygen. A ideia é usar a saída XML do Doxygen e alimentá-la ao Sphinx para gerar sua API. Assim, você pode manter todas as virtudes do Doxygen e unificar o sistema de documentação no Sphinx. Impressionante em teoria. Agora, na prática, a última vez que verifiquei o projeto não estava pronto para produção.
• pydoctor *: Muito particular. Gera sua própria saída. Possui alguma integração básica com o Sphinx e alguns recursos interessantes.

O Sphinx é principalmente uma ferramenta para formatar documentos escritos independentemente do código-fonte, pelo que entendi.

Para gerar documentos API a partir de docstrings Python, as principais ferramentas são pdoc e pydoctor . Aqui estão os documentos API gerados pelo pydoctor para Twisted e Bazaar .

Claro, se você quiser apenas dar uma olhada nas docstrings enquanto está trabalhando, existe a ferramenta de linha de comando " pydoc " e também a help()função disponível no interpretador interativo.

Outra ferramenta de documentação muito boa é o sphinx . Ele será usado para a próxima documentação do python 2.6 e é usado pelo django e muitos outros projetos do python.

No site da esfinge:

• Formatos de saída : HTML (incluindo Windows HTML Help) e LaTeX, para versões de PDF para impressão
• Referências cruzadas extensas : marcação semântica e links automáticos para funções, classes, termos de glossário e informações semelhantes
• Estrutura hierárquica : fácil definição de uma árvore de documentos, com links automáticos para irmãos, pais e filhos
• Índices automáticos : índice geral, bem como índice de módulo
• Manuseio de código : realce automático usando o iluminador Pygments
• Extensões : teste automático de snippets de código, inclusão de docstrings de módulos Python e muito mais