Bonjour
j'ai besoin de générer une doc pour mon code python
vous avez une idée sur la procédure d'utilisation de sphinx ou pydoc ou n'importe autre logiciel de doc :calim2:
merci
Version imprimable
Bonjour
j'ai besoin de générer une doc pour mon code python
vous avez une idée sur la procédure d'utilisation de sphinx ou pydoc ou n'importe autre logiciel de doc :calim2:
merci
j'ai installé sphinx
et j'ai suivi ce lien pour générer mon code
mais il me crée le répertoire et dedans je ne trouve mas la doc généré
en effet en tapant la commande :je ne vois pas exactement là on doit renseigner le chemin de notre code source pour que la doc soit généréeCode:sphinx-quickstart
merci de votre aide
Salut,
Après sphinx-quickstart, édite le fichier index.rst ou index.txt selon ton choix
et ajoute les noms des modules que tu veux documenter.
Exemple:
où module_1 est le nom du fichier .py sans l'extension et MaClass1 le nom de la classe à documenter et qui se trouve, bien sur, dans le fichier module_1.pyCode:
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17... Contents: .. toctree:: :maxdepth: 2 .. automodule:: module_1 .. autoclass:: MaClass1 :members: .. automodule:: module_2 .. autoclass:: MaClass2 :members:
:members: indique à Sphinx d'extraire les doc strings de toutes les fonctions de cette classe.
Ensuite, AVANT de faire 'make html', met à jour le path de python:
Puis tu peux faire make. Si tu as laissé les options par défaut, tu trouveras un fichier index.xxx dans _build/html. Au cas où tu as choisis html.Code:
2
Ne te décourage pas, on s'arrache un peu les cheveux au début.
En fait le principal est dans le fichier index.xxx
Un exemple concret:
http://docs.python.org/howto/index.html
clique sur 'Show Source'.
Salut
Pour epydoc, c'est
Perso je rajoute les options "--graph=classtree" qui crée un arbre hiérarchique des appels et "--src-code-tab-width=4" qui met les tabulations de mes sources à 4 espacesCode:epydoc -v -o <rep doc> [options en plus] liste_des_sources_ou_liste_des_dossiers_contenant_les_sources
je n'ai pas le fichier index.xxxCitation:
Envoyé par VinsS
j'ai un fichier index.html mais quand je l'ouvre je ne vois pas mes commentaires écrites dans mes classes :?
Tes commentaires non, mais tes docs string ?
oui c ca je me suis mal exprimé c tout
il doit généré tout ce qui est écrit dans mon code de cette manière
mais c fichier index.xxx je le vois pas et dans mon fichier index.html je ne vois aucun docs généréCode:
2
3
Bonjour,
Si tu n'y arrives pas avec Sphinx, essaie avec epydoc: c'est ce que j'utilise, et c'est assez simple pour fournir une documentation en html (code compris).
Salut,
D'abord index.xxx cela voulais dire index.txt ou index.rst par exemple.
En tout cas pas index.html, parce que cela veut dire que tu as déjà fait "make html"
Reprenons.
Tu as un dossier vide (j'insiste, vide) que tu appelle "docSphinx" par exemple.
Dans ce dossier, tu ouvres une console, et tu fais:
Tu donnes le nom de ton projet avec la bonne casse, il sera utilisé tel quel dans les titres de la doc, tu donnes ton nom, le copyright par défaut sera 2011. Ensuite, tu acceptes toutes les autres options par défaut, sinon ça foutra le boxon.Code:
2
Après cela, ton dossier qui était vide doit contenir ceci:
_build (dossier)
_static (dossier, vide)
_template (dossier, vide)
conf.py (script python)
index.txt (texte)
Tu édites ce dernier fichier texte
Soit tu veux uniquement extraire les docs strings de tes classes.Citation:
.. test1 documentation master file, created by
sphinx-quickstart on Mon Jun 6 16:56:05 2011.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to test1's documentation!
=================================
Contents:
.. toctree::
:maxdepth: 2
!! C'est ici que tu dois lui décrire sa matière ''
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Exemple, le fichier "machin.py" contient la classe "Machin"
ça donne ceci:
donc automodule >> nom du fichier sans l'extensionCitation:
.. test1 documentation master file, created by
sphinx-quickstart on Mon Jun 6 16:56:05 2011.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to test1's documentation!
=================================
Contents:
.. toctree::
:maxdepth: 2
.. automodule:: machin
.. autoclass:: Machin
:members:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
et autoclass >> nom de la classe
Attention dans ce fichier index.txt, les indentations sont de trois espaces.
Il te faut donc autant d'automodule que de fichiers python et autant d'autoclass que de classes.
Autre cas, tu as écrit une doc, en .rst par exemple, tu ajoutes ce fichier au dossier "docSphinx" (pas dans un sous-dossier, hein) et tu modifies le fichier index.txt comme ceci:
Ici , "class Machin" est le titre que je veux que Sphinx utilise pour cette doc et dans le menu de navigation et <doc_machin> le texte que j'ai écrit "doc_machin.rst"Citation:
.. test1 documentation master file, created by
sphinx-quickstart on Mon Jun 6 16:56:05 2011.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to test1's documentation!
=================================
Contents:
.. toctree::
:maxdepth: 2
class Machin <doc_machin>
class Truc <doc_truc>
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Tu peux mélanger les deux cas de figure. (Pas sur que je te donne un bon conseil :))
Après modification du fichier index.txt, tu fait avant toute chose
Ensuite tu peux faireCode:
2
Si tu obtiens ceci:Code:
2
c'est qu'il n'a pas trouvé les fichiers là où tu l'as indiqué dans le PYTHONPATH.Code:
2
Si tu tiens à refaire ceci dans le dossier que tu as déjà créé dans tes essais précédents vide le dossier _build, sans quoi Sphinx pourrais refuser de recréer certains fichiers.
Au boulot.
ya un problème là ,Citation:
Envoyé par VinsS
quand je faisen dehors du dossier Python26\Scripts ça marche plus , un message d'erreur: sphinx-quickstart no reconnu en tant que commande externe ou interne .Code:sphinx-quickstart
je suis obligé de faire cette commande dans python26/Scripts , si je le fais dans n'importe quel autre dossier le message d'erreur s'affiche
ça veut dire quoi ça ? est ce un problème d'installation ou de configuration ?
Ha, c'est un truc à la Windows ça.
Si un windowsien passe par ici ...
(Si il en reste)
j'ai essayé epydoc mais il génère plusieurs fichiers pour chaque classeCitation:
Envoyé par tyrtamos
et moi j'ai un nombre important de classes , donc epydoc ne m'arrange pas
il me faut un logiciel qui génère une seule fichier de documentation pour toutes mes classes
VinsS oui je suis sous windowsCitation:
Envoyé par VinsS
je passe par ou ? tu as oublié de coller le lien
Il y en a encore un peu plus de 90% :DCitation:
Envoyé par VinsS
@ nancy maman: essaie de faire précéder sphinx-quickstart par son chemin sur le disque:
Code:c:\chemin\sphinx-quickstart
je l'ai fais (C:\Python26\Scripts\sphinx-quickstart) et ça marche .Citation:
Envoyé par tyrtamos
maintenant le même problème revient quand je fais make html (sphinx-build n'est pas reconnu en tant que commande interne ou externe )
pourtant j'ai aussi donner le chemin sur mon disque
Code:C:\Python26\Scripts\make html
j'arrive à trouver ces dossier dans mon dossier docSphinx sauf que le dossier _build est videCitation:
Envoyé par VinsS
mon problème maintenant en lancant la commande make html il m'affiche le message d'erreur : sphinx-build n'est pas reconnu en tant que commande interne ou externe
Ce message d'erreur est rencontré quand la variable d'environnement PATH ne permet pas à Windows à savoir où se trouve ce programme.
En principe, c'est le programme d'installation du logiciel (ici sphinx) qui ajoute le chemin des exécutables du logiciel pour que Windows puisse le trouver. Par exemple, quand on lance "python" dans une console cmd, Windows regarde dans la variable PATH et lit qu'on peut le trouver dans c:\python27.
En résumé: il faut ajouter le chemin manquant dans PATH (=> panneau de configuration Windows).
le sphinx-build se trouve dans C:\Python26\Scripts
donc j'ai rajouté dans le PATH :mais toujours le même problèmeCode:C:\Python26\Scripts
Bonjour
Après avoir changé le path, il faut annuler la console et la relancer pour que le nouveau path soit pris en compte.
Bonjour,
d'accord
ca marche
mais les fichiers générés dans le _build\html contient un fichier index.html quand je l'ouvre je ne vois pas le text que j'ai écrit dans mon code source
le text je l'avais ecrit de cette maniere :
:cry:Code:
2
3
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
- puis, faireCode:
2
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!Code:make html
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!
Citation:
Envoyé par tyrtamos
(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.).Code:
2
3
4.. automodule:: monmodule :members: :show-inheritance:
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.
Bonjour valAa,
Merci! ça éclaire un peu, et j'arrive à en avoir plus qu'avant avec
Il reste de nombreux mots dont je ne comprends pas la signification, mais j'obtiens pour l'instant le minimum vital.Code:
2
3
4.. automodule:: monmodule :members: :undoc-members: :show-inheritance:
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!
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...
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.
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...