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