Discussion :

[NikeOfAllTrades]

Bonjour à tous.

J'écris ce post car, en dépit du fait que bien des personnes rencontrent le même problème, je ne suis pas parvenu à y trouver une solution claire et définitive sur google comme sur ce même forum.

Je cherche un générateur de documentation pour python. J'entends par la un bon générateur, avec lequel on peut créer toute la documentation d'un projet, pour chaque package/module/classe/attribut/fonction/argument de fonction (je suis un habitué de Javadoc ).

Je me suis naturellement tourné vers le générateur de doc officiel, pydoc. Dans un premier temps, je ne trouve étrangement aucune doc sur la façon d'écrire la doc à l'intérieur des docstrings, ou encore de documenter les attributs des classes ou des arguments de fonctions. Je cherche encore, y compris dans la doc officielle, rien. Je tombe finalement sur une obscure PEP, liée à plein d'autres toutes aussi obscures.

Après plus de recherches, j'en suis venu aux conclusions suivantes:
- pydoc est très pauvre en fonctionnalité, et le peu qu'il en possède sont de toutes façon méconnues de la plupart des développeurs car mal documentées
- il est peu pratique pour générer de la doc d'un projet, ne permettant notamment pas de la générer pour tout un projet, juste pour des modules séparés

Au vu des ces conclusions (qui pourraient être fausses remarquez, j'ai pas passé trois jours dessus), deux questions me viennent:
- Est-ce que, comme je le pense, pydoc est vraiment aussi minable, ce qui impliquerait donc qu'il soit inutilisable pour générer la doc de projets sérieux?
- Dans ce cas, quelles alternatives conseillez vous?

Merci d'avance à ceux qui répondront

[kango]

bonjour,

epydoc: http://epydoc.sourceforge.net/

exemple de doc générée avec:

http://www.lag.net/paramiko/docs/

epydoc a la particularité de reconnaitre 4 types de 'langage' pour les doctrings:

- plain text
- epytext (un langage à balise léger)
- reStructuredText
- javadoc

et est capable notamment de générer de la doc au format html (customisable avec des feuilles de style css) et pdf (par l'intermédiaire de Latex).

[pacificator]

Bonjour,

tu peux aussi essayer doxygen.

[dividee]

Il y a aussi sphynx, utilisé pour la documentation officielle de Python et de plus en plus d'autres projets.

[NikeOfAllTrades]

J'avais repéré ces trois la, maintenant le tout c'est de savoir lequel est le meilleur Quelqu'un a un dé à 3 faces?

[kango]

non juste epydoc pour ma part mais je suis très très intéresse par sphinx !

par contre je pense que cela ne sera pas en remplacement d'epydoc: ce sera epydoc pour les API et sphinx pour des exemples, tutoriaux, user manual etc...

[.Nawak]

Quelqu'un a un dé à 3 faces?

sur 1d6 :
1,2 : 1
3,4 : 2
5,6 : 3

[kango]

rhooo:

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
import random
print random.randint(1,3)

[NikeOfAllTrades]

En gros voici mes conclusions:

- Doxygen: je connais bien en C++ et, pour ce langage, c'est génial. Mais d'après plusieurs utilisateurs et même d'après la doc officielle le support python est mauvais, le parser python n'est pas au point et ne gère pas correctement les doc strings.
- Sphinx: dixit quelque part dans la doc, c'est un outil de documentation de projet et pas d'API. Il sert principalement à assembler plein de bouts de textes en restructuredtext. Apparemment il peut aussi aller chercher ces bouts dans le code python mais je n'aime pas cette idée. Ça permet uniquement de mettre du RST dans du python et rien d'autre, c'est à dire qu'il ne permet pas un marquage sémantique (il est par exemple impossible d'indiquer le type d'un argument dans un tag spécique) et pas non plus de liens entre différentes sections (ou alors j'ai pas trouvé).
- Epydoc: très proche de javadoc, voir même mieux. Permet un marquage sémantique, est ultra simple à utiliser (un petit «epydoc ./» et c'est bon). On regrettera juste que le créateur ait repris le look par défaut de la javadoc format html (vous savez, le truc moche avec des cadres).

Ce sera donc Epydoc qui m'aura convaincu le plus. Ce qui serait classe c'est un outil de conversion de epytext vers RST de façon à faire tous ses docstrings en epytext puis faire une doc avec sphinx le jour où on décide de faire une vrai doc de pro, pas du 100% auto-généré. Ca me semble faisable mais je n'ai rien trouvé pour ça, dommage

[arnaudk]

Merci pour ce retour, je pourrai donc fixer mes priorités pour mes propres tests.

[kango]

On regrettera juste que le créateur ait repris le look par défaut de la javadoc format html (vous savez, le truc moche avec des cadres).

les cadres html sont optionnels (en visualisant, tu peux les désactiver en cliquant sur 'no-frame') et l'option --css de epydoc permet de donner une autre feuille de style.