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?
Respostas:
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.
"""
passNesse 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():
passNesse 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 *.
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 .
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).
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.Existem outras opções a serem observadas:
__all__variável explicita.
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: