générer une documentation python

**nancy maman** · 23/09/2011, 11h47

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

merci

**nancy maman** · 23/09/2011, 14h40

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 :

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

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

**VinsS** · 24/09/2011, 11h52

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 :

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

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 :

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

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

**Sve@r** · 24/09/2011, 15h56

Salut

Pour epydoc, c'est

Code :

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

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

**nancy maman** · 26/09/2011, 10h22

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

**VinsS** · 26/09/2011, 14h39

Tes commentaires non, mais tes docs string ?

**nancy maman** · 27/09/2011, 11h24

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 :

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

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é

**tyrtamos** · 27/09/2011, 11h55

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

**VinsS** · 27/09/2011, 12h07

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 :

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

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

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

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

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

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

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

Ensuite tu peux faire

Code :

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

1
2
 
$ make html

Si tu obtiens ceci:

Code :

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

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.

**nancy maman** · 27/09/2011, 13h26

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 :

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

1
2
 
sphinx-quickstart

ya un problème là ,
quand je fais

Code :

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

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 ?

**VinsS** · 27/09/2011, 13h57

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

Si un windowsien passe par ici ...

(Si il en reste)

**nancy maman** · 27/09/2011, 14h10

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

**nancy maman** · 27/09/2011, 14h11

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

**tyrtamos** · 27/09/2011, 14h21

Envoyé par VinsS

Si un windowsien passe par ici ...

(Si il en reste)

Il y en a encore un peu plus de 90%

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

Code :

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

c:\chemin\sphinx-quickstart

**nancy maman** · 27/09/2011, 14h40

Envoyé par tyrtamos

Il y en a encore un peu plus de 90%

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

Code :

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

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 :

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

C:\Python26\Scripts\make html

**nancy maman** · 27/09/2011, 14h51

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 :

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

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

**tyrtamos** · 27/09/2011, 17h47

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

**nancy maman** · 28/09/2011, 09h53

le sphinx-build se trouve dans C:\Python26\Scripts
donc j'ai rajouté dans le PATH :

Code :

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

C:\Python26\Scripts

mais toujours le même problème

**tyrtamos** · 28/09/2011, 12h53

Bonjour

Après avoir changé le path, il faut annuler la console et la relancer pour que le nouveau path soit pris en compte.

**nancy maman** · 28/09/2011, 13h46

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 :

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

1
2
3
"""
       text 
     """

générer une documentation python

Python

Discussions similaires

Partager

Partager