générer une documentation python

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 :

Code:

---

sphinx-quickstart

---

je ne vois pas exactement là on doit renseigner le chemin de notre code source pour que la doc soit générée
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:

Code:

---

1 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:

---

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.py
: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:

Code:

---

1 2	$ export PYTHONPATH=$PYTHONPATH:/chemin/de/mon/projet

---

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.

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

Code:

---

epydoc -v -o <rep doc> [options en plus] liste_des_sources_ou_liste_des_dossiers_contenant_les_sources

---

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 espaces

Citation:

---

Envoyé par VinsS

tu trouveras un fichier index.xxx dans _build/html. Au cas où tu as choisis html.

---

je n'ai pas le fichier index.xxx
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

Code:

---

1 2 3

"""       classe : documentation        """

---

mais c fichier index.xxx je le vois pas et dans mon fichier index.html je ne vois aucun docs généré

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:

Code:

---

1 2	sphinx-quickstart

---

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.

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

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`

---

Soit tu veux uniquement extraire les docs strings de tes classes.

Exemple, le fichier "machin.py" contient la classe "Machin"

ça donne ceci:

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

.. automodule:: machin

.. autoclass:: Machin
:members:

Indices and tables
==================


* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

---

donc automodule >> nom du fichier sans l'extension
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:

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`

---

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"

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

Code:

---

1 2	$ export PYTHONPATH=$PYTHONPATH:/chemin/de/mon/projet

---

Ensuite tu peux faire

Code:

---

1 2	$ make html

---

Si tu obtiens ceci:

Code:

---

1 2	...(WARNING/2) autodoc can't import/find module 'viewing', it reported error: "No module named viewing", please check your spelling and sys.path

---

c'est qu'il n'a pas trouvé les fichiers là où tu l'as indiqué dans le PYTHONPATH.

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.

Citation:

---

Envoyé par VinsS

Tu as un dossier vide (j'insiste, vide) que tu appelle "docSphinx" par exemple.

Dans ce dossier, tu ouvres une console, et tu fais:

Code:

---

1 2	sphinx-quickstart

---

---

ya un problème là ,
quand je fais

Code:

---

sphinx-quickstart

---

en dehors du dossier Python26\Scripts ça marche plus , un message d'erreur: sphinx-quickstart no reconnu en tant que commande externe ou interne .
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)

Citation:

---

Envoyé par tyrtamos

Bonjour,

essaie avec epydoc: c'est ce que j'utilise, et c'est assez simple pour fournir une documentation en html (code compris).

---

j'ai essayé epydoc mais il génère plusieurs fichiers pour chaque classe
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

Citation:

---

Envoyé par VinsS

Ha, c'est un truc à la Windows ça.

Si un windowsien passe par ici ...

(Si il en reste)

---

VinsS oui je suis sous windows
je passe par ou ? tu as oublié de coller le lien

Citation:

---

Envoyé par VinsS

Si un windowsien passe par ici ...

(Si il en reste)

---

Il y en a encore un peu plus de 90% :D

@ nancy maman: essaie de faire précéder sphinx-quickstart par son chemin sur le disque:

Code:

---

c:\chemin\sphinx-quickstart

---

Citation:

---

Envoyé par tyrtamos

Il y en a encore un peu plus de 90% :D

@ 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 .
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

---

Citation:

---

Envoyé par VinsS

Tu as un dossier vide (j'insiste, vide) que tu appelle "docSphinx" par exemple.

Dans ce dossier, tu ouvres une console, et tu fais:

Code:

---

1 2	sphinx-quickstart

---

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.

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)

---

j'arrive à trouver ces dossier dans mon dossier docSphinx sauf que le dossier _build est vide
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 :

Code:

---

C:\Python26\Scripts

---

mais toujours le même problème

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 :

Code:

---

1 2 3

"""        text      """

---

:cry: