Discussion :

[nancy maman]

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]

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]

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

[nancy maman]

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]

Tes commentaires non, mais tes docs string ?

[nancy maman]

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é

[Sve@r]

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