Discussion :

[tyrtamos]

Mon expérience de Sphinx:

Par curiosité, je viens de passer 3 heures à installer, configurer et utiliser Sphinx, et ma conclusion, c'est que ce logiciel est une véritable punition.

J'ai appliqué ce que j'ai vu dans la doc, dans le présent fil ainsi que dans une vingtaine de pages web.

Pour installer sphinx sous Windows, il faut installer:
- setuptools (pour avoir easy_install, nécessaire pour installer les .egg)
- docutils (pour avoir reStructuredText)
- Jinja2
- Pygments
- puis, enfin, Sphinx

Une fois installé tout ça, il faut:

- ajouter à la main le chemin des binaires c:\Python27\Scripts dans le path de windows, et mettre à jour ou créer le PYTHONPATH qui doit pointer sur le répertoire contenant le module à documenter (panneau de configuration => system).

- créer le répertoire de la future doc

- Dans une console, se placer dans le répertoire de la future doc, et faire sphinx-quickstart. Répondre aux différentes questions (automodule=yes).

- modifier index.rst et ajouter

Code :

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

1
2
.. automodule:: monmodule
.. autoclass:: laclassedemonmodule

- puis, faire

Code :

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

make html

A la fin, il me sort une superbe page html dans laquelle il me répète le nom du module que je lui ai donné (bravo!), la classe que je lui ai donnée dans ce module (même pas fichu de la trouver tout seul?) et le docstring de cette classe (seul travail utile qu'il a fait). Mais rien d'autre!

Tout ça pour ça?

Que faut-il faire pour avoir tout le reste: les fonctions et les méthodes avec leurs docstring, les ascendances des classes, les variables globales, les importations, etc...???

J'aimerais bien obtenir de Sphinx AU MOINS ce que j'ai obtenu facilement avec epydoc.

Merci d'avance au bienfaiteur qui pourra me donner un coup de pouce!

[valAa]

Que faut-il faire pour avoir tout le reste: les fonctions et les méthodes avec leurs docstring, les ascendances des classes, les variables globales, les importations, etc...???

Code :

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

1
2
3
4
 
.. automodule:: monmodule
    :members:
    :show-inheritance:

(par exemple, mais ça dépend de ce que tu veux, mettre les membres privés ou pas, les membres hérités ou pas, etc.).
Bref, c'est là :
http://sphinx.pocoo.org/ext/autodoc....nx.ext.autodoc

edit:
J'utilise les deux (epydoc et sphinx) et il faut bien voir que leurs cas d'utilisation ne sont pas vraiment les mêmes.

Si le but est d'extraire la doc complète d'une API via son code en reflétant sa structure, la mettre en HTML "et pi c'est tout" à la doxygen, epydoc est bien plus efficace.

Si le but est de construire un site de documentation d'un projet, avec des manuels, avec une documentation de l'API parfois déconnectée de l'organisation réelle du code, etc, epydoc ne le permet pas, sphinx si. Évidemment ça demande de taper du restructured text.

Comme d'habitude, la problématique est de choisir l'outil le plus adapté au besoin.

[tyrtamos]

Bonjour valAa,

Merci! ça éclaire un peu, et j'arrive à en avoir plus qu'avant avec

Code :

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

1
2
3
4
.. automodule:: monmodule
    :members:
    :undoc-members:
    :show-inheritance:

Il reste de nombreux mots dont je ne comprends pas la signification, mais j'obtiens pour l'instant le minimum vital.

Mon besoin est limité à la phase de développement et à celle de maintenance: j'ai un logiciel de 10000 lignes découpé en une quinzaine de modules, et j'ai besoin d'un outil me permettant d'avoir en même temps une vue d'ensemble et d'avoir une facilité de recherche (dans quel module ais-je mis la fonction xxx) avec renvoi au code.

Actuellement, j'utilise seulement un petit logiciel de recherche de texte que j'ai développé en PyQt4 et dont je me sers pour chercher des mots dans les fichiers de code (dans une arborescence donnée), et qui me donne les fichiers trouvés et les numéros de lignes. C'est déjà quelque chose, mais ça ne me suffit pas.

Epydoc était pour moi une bonne surprise, car la version html est facile à obtenir et fournit beaucoup d'infos avec le renvoi au code source. Grâce au logiciel Graphviz, Epydoc fournit même une représentation graphique des ascendances des classes.

La version pdf, plus difficile à obtenir (il faut latex: j'ai pris MiKTex), est impressionnante aussi: appliquée à mon logiciel, j'obtiens un pdf de plus de 100 pages très structuré avec les modules et les classes, la table des matières et les index (renvois par liens hypertextes!). Malheureusement, le pdf exclut le lien avec le code source, et je préfère le html pour cette raison.

En fait, la seule chose qui m'inquiète dans Epydoc, c'est qu'il n'a pas bougé depuis janvier 2008: d'où ma curiosité pour Sphinx...

Merci encore pour le coup de pouce!

[Beginner.]

Salut,

Je suis tombé sur cet ancien fil...

J'aimerais savoir si vous connaissez un équivalent à Epydoc pour python 3 ?
Ce serait pour générer la doc complète avec toutes les classes et leur hiérarchie...

Je voudrais cela pour tkinter et matplotlib...
Exemple : http://epydoc.sourceforge.net/stdlib/ (dans lequel il y a notamment le module tkinter)

Merci.

PS : sphinx c'est trop compliqué apparemment...

[tyrtamos]

Bonjour,

Je ne l'ai pas encore essayé, mais peut-être faut-il regarder du côté de pydoctor (https://pypi.org/project/pydoctor/) qui dit pouvoir remplacer epydoc pour Python 3. A noter que epydoc n'a toujours pas bougé depuis 2008.

[Beginner.]

Merci, je vais regarder cela...

Sinon oui Epydoc ne semble pas fonctionner avec Python 3 d'où ma recherche d'un équivalent...

PS: J'ai réussi à faire fonctionner pdoc mais c'est moins bien qu'Epydoc...