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