Puis-je document code Python avec doxygen (et du sens)?

Question

J'aime doxygen pour créer de la documentation du C ou du code PHP. J'ai un prochain projet de Python et je pense que je me souviens que Python n'est pas /* .. */ commentaires et possède également sa propre auto-documentation de l'installation qui semble être le pythonic façon de document.

Puis-je utiliser doxygen? Rien de particulier à être au courant?

J'ai fait un peu de codage en Python mais seulement sur de petits projets où j'ai été trop paresseux pour le document à tous (oui, je sais ... mais nous allons juste faire semblant que c'est OK pour l'instant).

Answer 1

C'est documenté sur le doxygen site web, mais de résumer ici:

Vous pouvez utiliser doxygen pour documenter votre code Python. Vous pouvez soit utiliser la documentation Python syntaxe de la chaîne:

"""@package docstring
Documentation for this module.

More details.
"""

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

    More details.
    """
    pass

Auquel cas, les commentaires seront extraites par doxygen, mais vous ne serez pas en mesure d'utiliser l'un de l' spéciale doxygen commandes.

Ou vous pouvez (similaire à C-style de langues sous doxygen) double la marque de commentaire (#) sur la première ligne, avant que le membre:

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

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

Dans ce cas, vous pouvez utiliser le doxygen commandes. Il n'y a pas particulier Python mode de sortie, mais vous pouvez apparemment d'améliorer les résultats en définissant OPTMIZE_OUTPUT_JAVA de YES.

Honnêtement, je suis un peu surpris de la différence, il semble que une fois que doxygen peut détecter les commentaires dans les # # # blocs ou """ blocs, la plupart des travaux et vous seriez en mesure d'utiliser les commandes spéciales dans les deux cas. Peut-être qu'ils attendent les gens à l'aide de """ d'adhérer à plus d'Pythonic les pratiques de documentation et qui pourrait interférer avec le spécial doxygen commandes?

Answer 2

Sphinx est principalement un outil pour la mise en forme docs écrits de façon indépendante à partir du code source, ce que je comprends.

Pour générer les docs de l'API à partir de Python docstrings, les principaux outils sont Epydoc et pydoctor. Voici pydoctor généré les docs de l'API pour les Tordus et de Bazar.

Bien sûr, si vous voulez juste avoir un regard sur les docstrings pendant que vous travaillez sur des trucs, il y a la "pydoc" outil de ligne de commande ainsi que l' help() les fonctions disponibles dans le interactive interprète.

Answer 3

Un autre très bon outil de documentation est le sphinx. Il sera utilisé pour la prochaine version 2.6 de python de la documentation , et est utilisé par django et beaucoup d'autres python projets.

Du sphinx site web:

• Formats de sorties: HTML (y compris les Windows HTML Help) et de LaTeX, pour imprimable version PDF
• Vaste de la croix-des références: le balisage sémantique et automatique des liens pour les fonctions, les classes, les termes du glossaire et des informations semblables
• Structure hiérarchique: facile définition de l'arborescence du document, avec des liens automatiques vers des frères et sœurs, les parents et les enfants
• Automatique indices: indice général, ainsi qu'un module d'index
• Code de la manipulation: mise en évidence automatique à l'aide de la Pygments surligneur
• Extensions: contrôle automatique de fragments de code, l'inclusion des docstrings de modules Python, et plus