Comment documenter le code Python avec doxygen [fermé]

Question

J'aime que doxygen crée de la documentation sur du code C ou PHP.J'ai un projet Python à venir et je pense que je me souviens que Python n'a pas /* .. */ commentaires, et possède également sa propre fonction d'auto-documentation qui semble être la manière pythonique de documenter.

Puisque je connais doxygen, comment puis-je l'utiliser pour produire ma documentation Python ?Y a-t-il quelque chose en particulier dont je dois être conscient ?

Answer 1

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

Vous pouvez utiliser doxygen pour documenter votre code Python.Vous pouvez soit utiliser la syntaxe de chaîne de la 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 aucun des commandes spéciales doxygen.

Ou vous pouvez (semblable aux langages de style C 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 définissant OPTMIZE_OUTPUT_JAVA à YES.

Honnêtement, je suis un peu surpris de la différence - il semble qu'une fois que doxygen peut détecter les commentaires dans les blocs ## ou les blocs """, la plupart du travail serait fait et vous pourriez utiliser les commandes spéciales dans dans tous les cas.Peut-être qu'ils s'attendent à ce que les personnes utilisant """ adhèrent à des pratiques de documentation plus Pythoniques et que cela interférerait avec les commandes spéciales doxygen ?

Answer 2

Le doxypie Le filtre d'entrée vous permet d'utiliser à peu près toutes les balises de formatage de Doxygen dans un format docstring Python standard.Je l'utilise pour documenter un grand framework d'application de jeu mixte C++ et Python, et cela fonctionne bien.

Answer 3

Sphinx est principalement un outil de formatage de documents écrits indépendamment du code source, si je comprends bien.

Pour générer des documents API à partir de docstrings Python, les principaux outils sont pdoc et pydocteur.Voici la documentation API générée par pydoctor pour Tordu et Bazar.

Bien sûr, si vous voulez juste jeter un œil aux docstrings pendant que vous travaillez sur des trucs, il y a le "pydoc" outil de ligne de commande et ainsi que l' help() fonction disponible dans l’interprète interactif.

Answer 4

Au final, vous n'avez que deux options :

Vous générez votre contenu à l'aide de Doxygen, ou vous générez votre contenu à l'aide de Sphinx*.

1. Doxygène:Ce n'est pas l'outil de choix pour la plupart des projets Python.Mais si vous devez gérer 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 doxypypie.

2. Sphinx:L'outil de facto pour documenter un projet Python.Vous avez trois options ici :manuel, semi-automatique (génération de stub) et entièrement automatique (comme Doxygen).

   1. Pour la documentation manuelle de l'API, vous disposez de Sphinx autodoc.C'est formidable d'écrire un guide de l'utilisateur avec des éléments générés par l'API intégrés.
   2. Pour les semi-automatiques, vous avez Sphinx résumé automatique.Vous pouvez soit configurer votre système de build pour appeler sphinx-autogen, soit configurer votre Sphinx avec le autosummary_generate configuration.Vous devrez configurer une page avec les résumés automatiques, puis modifier 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 bugs et l'impossibilité de déterminer exactement ce qui était exposé en tant qu'API publique et ce qui ne l'était pas.Mon avis est que cet outil est bon pour la génération de stub qui nécessitera une édition manuelle, et rien de plus.C'est comme un raccourci pour finir en manuel.
   3. Entièrement automatique.Cela a été critiqué à plusieurs reprises et pendant longtemps nous n'avons pas eu de bon générateur d'API Python entièrement automatique intégré à Sphinx jusqu'à ce que API automatique est venu, qui est un nouveau venu dans le quartier.C'est de loin le meilleur pour la génération automatique d'API en Python (remarque :auto-promotion éhontée).

Il existe d'autres options à noter :

• Respirer:cela a commencé comme une très bonne idée et a du sens lorsque vous travaillez avec plusieurs projets connexes dans d'autres langages 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 conserver tous les avantages de Doxygen et unifier le système de documentation dans Sphinx.Génial en théorie.En pratique, la dernière fois que j'ai vérifié, le projet n'était pas prêt pour la production.
• pydocteur* :Très particulier.Génère sa propre sortie.Il a une intégration de base avec Sphinx et quelques fonctionnalités intéressantes.

Answer 5

Un autre très bon outil de documentation est sphinx.Il sera utilisé pour le prochain python 2.6 Documentation et est utilisé par Django et beaucoup d'autres projets Python.

Sur le site du sphinx :

• Formats de sortie:HTML (y compris l'aide HTML de Windows) et LaTeX, pour les versions PDF imprimables
• De nombreuses références croisées:balisage sémantique et liens automatiques pour les fonctions, classes, termes de glossaire et informations similaires
• Structure hiérarchique:définition facile d'une arborescence de documents, avec des liens automatiques vers les frères et sœurs, les parents et les enfants
• Index automatiques:index général ainsi qu'un index des modules
• Gestion des codes:mise en évidence automatique à l'aide du surligneur Pygments
• Rallonges:test automatique d'extraits de code, inclusion de docstrings à partir de modules Python, etc.