Quelle est la relation entre docutils et Sphinx?
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 les documents Python officiels. Quelqu'un peut-il trier l'état actuel des outils de documentation de Python pour moi?
3 réponses
Epydoc et Sphinx sont les différents types d'outils.
Ils sont les mêmes en ce qu'ils:
- Fois l'utilisation de Reste par docutils.
- Les deux sont très pythoniques dans leur foyer
- les deux peuvent générer de la documentation HTML et PDF
Ils sont différents dans leur foyer.
- Epydoc se concentre sur la documentation de L'API (développeur). 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 je veux d'un outil de documentation API.
- Sphinx se concentre sur la documentation générale (utilisateur). Alors que Sphinx tire beaucoup d'informations de votre code source, vous devez en mettre un peu plus. Sphinx peut générer de la documentation API, mais ce n'est pas aussi simple, et IMO ne fait pas aussi bon travail Qu'Epydoc. Je sais que certains ne seront pas d'accord parce que Sphinx est choisi pour Python . Mais, cela dépend de la quantité de travail que vous voulez y mettre. Je faire l'amour 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.
J'ai récemment changé de Python2 en Python3 et j'ai trouvé qu'il n'y avait pas de paquet Epydoc pour Python3. Il semble donc qu'avec Python3, il y ait un accent clair sur L'utilisation de Sphinx comme documentation de L'API.
Il semble que Epydoc soit, sinon mort, au moins languissant pour les fjords.
Sphynx avec la commandesphinx-apidoc et l'extensionautodoc semble être l'option la plus populaire pour les documents API en ce moment.
Les bons exemples sont:
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 javadoc, mais peut-être que c'est une bonne chose?