Il semble y avoir une pléthore d'outils de documentation pour Python. Un autre que j'ai rencontré est epydoc. Il semble que Sphinx soit le standard de facto, car il est utilisé pour générer la documentation officielle de Python. Quelqu'un peut-il faire le point pour moi sur l'état actuel des outils de documentation pour Python ?
Réponses
Trop de publicités?
epydoc y Sphinx sont différents types d'outils.
Ils sont identiques en ce qu'ils :
- Les deux utilisent ReST via docutils .
- Les deux sont très pythoniques dans leur approche
- Tous deux peuvent générer des documents HTML et PDF
Ils sont différents dans leur objectif.
- Epydoc est axé sur la documentation des API (développeurs). Vous obtenez plus de résultats plus rapidement avec Epydoc. Vous le pointez sur votre code source et vous obtenez quelque chose. C'est ce que j'attends d'un outil de documentation d'API.
- Sphinx est axé sur la documentation générale (utilisateur). Bien que Sphinx tire beaucoup d'informations de votre code source, vous devez en mettre un peu plus dans la documentation. Sphinx peut générer de la documentation d'API mais ce n'est pas aussi simple et, selon moi, il ne fait pas un aussi bon travail qu'Epydoc. Je sais que certains ne seront pas d'accord car Sphinx est choisi pour Python . MAIS, cela dépend de la quantité de travail que vous voulez y consacrer. J'aime beaucoup Sphinx pour la documentation générale.
Cela dépend donc de la quantité de travail que vous voulez y consacrer et de ce que vous documentez.
MrLeeh
Points
41
cbare
Points
1673
Il semble que Epydoc est, si ce n'est pas mort, du moins nostalgique des fjords.
Sphynx avec le sphinx-apidoc et la commande autodoc semble être l'option la plus populaire pour les documents d'API à l'heure actuelle.
De bons exemples :
Voir : Devrions-nous utiliser Epydoc, Sphinx ou autre chose pour documenter les API Python ? (SO5579198)
Sphinx encourage un style plus narratif que les outils dans le moule de la javadoc, mais peut-être est-ce une bonne chose ?
