Comment documenter le code Python avec doxygen [fermé]
j'aime que doxygen crée de la documentation de code C ou PHP. J'ai un projet Python à venir et je pense que je me souviens que Python n'a pas de commentaires /* .. */ , et a aussi sa propre facilité d'auto-documentation qui semble être la façon pythonique de documenter.
comme je suis familier avec doxygen, Comment puis-je l'utiliser pour produire ma documentation Python? Y a-t-il quelque chose en particulier que je dois savoir?
5 réponses
c'est documenté sur le site de doxygen , mais pour résumer ici:
vous pouvez utiliser doxygen pour documenter votre code Python. Vous pouvez utiliser la syntaxe de la chaîne de documentation Python:
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
dans ce cas, les commentaires seront extraits par doxygen, mais vous ne pourrez utiliser aucune des commandes spéciales doxygen .
Ou vous can (similaire à C-style languages sous doxygen) doubler le marqueur de commentaire ( # ) sur la première ligne avant 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 les commandes spéciales doxygen. Il n'y a pas de mode de sortie Python particulier, mais vous pouvez apparemment améliorer les résultats en paramétrant OPTMIZE_OUTPUT_JAVA à YES .
honnêtement, je suis un peu surpris de la différence - il semble qu'une fois doxygen peut détecter les commentaires dans ## des blocs ou des """ blocs, la plupart des travaux et vous seriez en mesure d'utiliser les commandes spéciales dans les deux cas. Peut-être s'attendent-ils à ce que les personnes utilisant "" adhèrent à des pratiques de documentation plus Pythoniques et qui interféreraient avec les commandes spéciales doxygen?
le filtre d'entrée doxypy vous permet d'utiliser à peu près toutes les balises de formatage de Doxygen dans un format de docstring Python standard. Je l'utilise pour documenter un grand cadre d'application mixte C++ et Python, et cela fonctionne bien.
Sphinx est principalement un outil pour formater des docs écrits indépendamment du code source, comme je le comprends.
pour générer des Doc API à partir de docstrings Python, les principaux outils sont pdoc et pydoctor . Voici les docs API générés par pydoctor pour Twisted et Bazaar .
bien sûr, si vous voulez juste avoir un regard sur les docstrings tout vous travaillez sur des trucs, il y a le" pydoc " outil en ligne de commande et aussi la fonction help() disponible dans l'interpréteur interactif.
à la fin, vous avez seulement deux options:
vous générez votre contenu en utilisant Doxygen, ou vous générez votre contenu en utilisant Sphinx*.
-
Doxygen : ce n'est pas l'outil de choix pour la plupart des projets Python. Mais si vous avez à traiter avec d'autres projets connexes écrits en C ou c++ cela pourrait avoir du sens. Pour cela, vous pouvez améliorer l'intégration entre Doxygen et Python en utilisant doxypy .
-
Sphinx : l'outil defacto pour documenter un projet Python. Vous avez trois options ici: manuel, semi-automatique (génération de talons) et entièrement automatique (comme Doxygen).
- pour la documentation API manuelle vous avez Sphinx autodoc . C'est génial pour écrire un guide de l'utilisateur avec des éléments générés par L'API intégrée.
- pour semi-automatique vous avez Sphinx autosummary . Vous pouvez soit configurer votre système de compilation pour appeler sphinx-autogen, soit configurer votre Sphinx avec la configuration
autosummary_generate. Vous devrez configurer une page avec les autosummaries, puis éditer manuellement les pages. Vous avez des options, mais mon expérience avec cette approche est qu'elle nécessite beaucoup trop de configuration, et à la fin, même après avoir créé de nouveaux modèles, j'ai trouvé des bogues et l'impossibilité de déterminer exactement ce qui était exposé en tant QU'API publique et ce qui ne l'est pas. Mon opinion est que cet outil est bon pour la génération de talon qui nécessitera l'édition manuelle, et rien de plus. C'est comme un raccourci pour finir en manuel. - entièrement automatique. Cela a été critiqué à de nombreuses reprises et pendant longtemps nous n'avons pas eu un bon générateur entièrement automatique D'API Python intégré avec Sphinx jusqu'à ce que AutoAPI soit venu, qui est un nouvel enfant dans le bloc. C'est de loin le meilleur pour la génération automatique D'API dans Python (note: honteless self-promotion).
il y a d'autres options pour noter:
- Breathe : cela a commencé comme une très bonne idée, et a du sens lorsque vous travaillez avec plusieurs projets connexes dans d'autres langues qui utilisent Doxygen. L'idée est d'utiliser la sortie XML de Doxygen et de la transmettre à Sphinx pour générer votre API. Ainsi, vous pouvez garder toute la bonté de Doxygen et unifier le système de documentation à Sphinx. Génial en théorie. Maintenant, dans la pratique, la dernière fois que j'ai vérifié le projet n'était pas prêt pour la production.
- pydoctor *: très particulier. Génère sa propre production. Il a une certaine intégration de base avec Sphinx, et quelques fonctionnalités intéressantes.
un autre très bon outil de documentation est sphinx . Il sera utilisé pour la prochaine Python 2.6 documentation et est utilisé par django et beaucoup d'autres projets python.
du sphinx site web:
- formats de sortie : HTML (incluant Windows HTML Help) et LaTeX, pour les versions PDF imprimables
- renvois extensifs : balisage sémantique et liens automatiques pour fonctions, classes, termes de glossaire et éléments d'information similaires
- 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
- indices automatiques : indice général ainsi qu'un indice de module
- Code manipulation : mise en évidence automatique à l'aide du pygments highlighter
- Extensions : test automatique d'extraits de code, inclusion de docstrings de modules Python, et plus