Como documento de código Python com doxygen [fechado]

StackOverflow https://stackoverflow.com/questions/58622

Pergunta

Eu gosto do doxygen para criar documentação de C ou código PHP.Eu tenho um próximo Python projeto e eu acho que eu me lembro de que o Python não tem /* .. */ comentários, e também tem a sua própria auto-documentação de instalações, que parece ser a pythonic forma de documento.

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

Foi útil?

Solução

Este é documentada no doxygen site, mas , para resumir aqui:

Você pode usar o doxygen para documentar seu código Python.Você pode usar o Python documentação sintaxe de seqüência de caracteres:

"""@package docstring
Documentation for this module.

More details.
"""

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

    More details.
    """
    pass

No caso, os comentários serão extraídos por doxygen, mas você não será capaz de usar qualquer um dos especial doxygen comandos.

Ou você pode (semelhante ao C-estilo de idiomas 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 o especial doxygen comandos.Não há particular Python modo de saída, mas você pode, aparentemente, melhorar os resultados, definindo OPTMIZE_OUTPUT_JAVA para YES.

Honestamente, eu estou um pouco surpreso com a diferença - parece que uma vez doxygen pode detectar os comentários em ## blocos ou blocos, a maioria do trabalho seria feito e você seria capaz de usar comandos especiais, em qualquer caso.Talvez eles esperam que as pessoas utilizando """ para aderir a mais Pythonic documentação práticas e que possam interferir com o especial do doxygen comandos?

Outras dicas

O doxypy filtro de entrada permite que você use muito do Doxygen as marcas de formatação em um padrão de Python docstring formato.Eu uso ele para documentar um grande misto C++ e Python jogo framework de aplicações, e ele está funcionando bem.

A esfinge é principalmente uma ferramenta para formatação de documentos escritos de forma independente a partir do código-fonte, como eu a entendo.

Para a geração da API do google docs a partir de Python docstrings, as principais ferramentas de são pdoc e pydoctor.Aqui está pydoctor gerados API do google docs para Torcida e Bazar.

Claro, se você só quer ter um olhar para o docstrings enquanto você está trabalhando em outras coisas, há o "pydoc"ferramenta de linha de comando e assim como o help() função disponível no interpretador interativo.

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

Você gerar o conteúdo utilizando o Doxygen, ou você gerar o seu conteúdo usando o Sphinx*.

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

  2. Esfinge:O facto ferramenta para documentar um Python projeto.Você tem três opções aqui:manual, semi-automático (stub geração) e totalmente automático (como o Doxygen).

    1. Manual da documentação da API que você tem Esfinge autodoc.Isso é ótimo para escrever um guia do usuário com o embedded API gerada elementos.
    2. Para semi-automático, você tem a Esfinge autosummary.Você pode configurar o seu sistema de compilação para chamar a esfinge-autogen ou configuração de sua Esfinge, com a autosummary_generate config.Você vai exigir a instalação de uma página com o autosummaries e, em seguida, edite manualmente as páginas.Você tem opções, mas a minha experiência com esta abordagem é que ela exige, e muito, configuração, e no final, mesmo após a criação de novos modelos, encontrei bugs e a impossibilidade de determinar exatamente o que foi exposto como API pública e o que não.A minha opinião é esta ferramenta é boa para o stub geração que vai exigir manual de edição, e nada mais.É como um atalho para acabar no manual.
    3. Totalmente automático.Este tem sido criticado muitas vezes e durante muito tempo não tínhamos um bom totalmente automático API Python do gerador integrado com a Esfinge até AutoAPI veio, que é um garoto novo no bloco.Este é de longe o melhor sistema automático de API de geração em Python (nota:auto-promoção descarada).

Existem outras opções para observação:

  • Respirar:isso começou como uma idéia muito boa, e faz sentido quando você trabalha com vários relacionados com o projeto em outros idiomas que usam o Doxygen.A ideia é usar o Doxygen XML de saída e alimentá-lo a Esfinge para gerar a sua API.Assim, você pode manter toda a bondade do Doxygen e unificar o sistema de documentação em Esfinge.Incrível em teoria.Agora, na prática, a última vez que eu chequei o projeto não estava pronto para produção.
  • pydoctor*:Muito particular.Gera sua própria saída.Ele tem alguns integração básica com a Esfinge, e alguns bons recursos.

Um outro muito bom ferramenta de documentação é esfinge.Ele será usado para o próximo python 2.6 documentação e é usado por django e um monte de outras python projetos.

A partir da esfinge site:

  • Formatos de saída:HTML (incluindo o Windows Ajuda em HTML) e Látex, para impressão em PDF versões
  • Extensas referências cruzadas:semântica e marcação automática de links para funções, classes, glossário de termos e semelhantes, peças de informação
  • Estrutura hierárquica:fácil de definição de uma árvore do documento, com ligações automáticas para irmãos, pais e filhos
  • Automática de índices:índice geral bem como um módulo do índice de
  • A manipulação do código:realce automático usando o Pygments o marcador
  • Extensões:teste automático de trechos de código com inclusão de docstrings a partir de módulos de Python, e muito mais
Licenciado em: CC-BY-SA com atribuição
Não afiliado a StackOverflow
scroll top