Discussion :

[Jackbalek]

Bonjour à tous.

Actuellement je souhaite générer une documentation de mon script en python avec Sphinx.
J'ai lu un tas de tuto là dessus, mais je ne vois pas encore comment générer automatiquement cette documentation à partir de mon script en python.

J'ai sphinx d'installé et pour l'instant j'obtiens la page html classique de sphinx.

J'ai lu quand faisant ainsi (voir ci dessous) cela pouvait fonctionner.

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
18
19
20
21
22
23
24
 
.. Homework documentation master file, created by
   sphinx-quickstart on Wed Jul 23 09:33:05 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.
 
Welcome to Homework's documentation!
====================================
 
Contents:
 
.. toctree::
   :maxdepth: 2
 
.. automodule:: "nom de mon fichier"
 
.. autoclass:: "nom de mes classes"
 
Indices and tables
==================
 
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Le problème que j'ai c'est que mon script en python ne possède pas de classe, mais uniquement des fonctions.
Et deuxième question comment la doc peut se générer sachant qu'à aucun moment je n'indique le path de mon script.

En espérant avoir été un maximum clair.
Je vous remercie d'avance.

[VinsS]

Salut,

Je ne l'ai jamais utiliser en autodoc, je préfère fournir la doc en .rst, mais la procédure est la même.

Tu crées dans ton appli un dossier doc, tu y mets ton fichier de config, tu ouvres une console dans ton appli et tu lance

Code :

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

1
2
 
sphinx-build -b html doc/ doc/_build/

Pour les classes, j'ignore comment ça se passe, mais rien ne t'empêche d'essayer en supprimer la ligne

Code :

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

1
2
 
.. autoclass:: "nom de mes classes"

du fichier de config.

[Jackbalek]

Merci pour cette réponse VinsS (et ce n'est pas la première).

Ce que je ne comprend pas, c'est où je place mon script. Doit-il rester dans un répertoire extérieur ou doit-je le mettre aussi dans le répertoire doc ?

[Petibidon]

Hello,

Ton script, tu le place un peu où tu veux. L'important c'est que sphinx puisse l'importer pour lire tes docstrings.
Pour cela tu dois éditer le fichier conf.py (qui doit se trouver dans ton dossier doc/source) et ajouter le chemin de ton script à sys.path. C'est la première directive après les imports, et le fichier conf.py est documenté pour te guider.

[Jackbalek]

Merci pour ta réponse, c'est bon j'ai trouvé.

Mais par contre je ne sais toujours pas comment faire pour générer automatiquement une doc.
A force de lire des tutos, j'ai l'impression que je vais devoir inclure une classe dans mon script (et ceci m'enchante que très peu...)

[Petibidon]

http://sphinx-doc.org/tutorial.html#autodoc

Pour ton script, automodule ou autofunction semblent pas mal adaptés

[Jackbalek]

Cette fonction autofunction semble pas mal du tout .

Alors voilà ce que j'ai écrit pour tester dans index.rst :

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
18
19
20
21
22
 
.. Homework documentation master file, created by
   sphinx-quickstart on Wed Jul 23 09:33:05 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.
 
Welcome to Homework's documentation!
====================================
 
Contents:
 
.. toctree::
   :maxdepth: 2
 
.. autofunction:: function_name 
 
Indices and tables
==================
 
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Mais voici ce qui me ramène quand je make le html:

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
18
19
 
sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.1.3
loading pickled environment... not yet created
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                 
/PATH/index.rst:14: WARNING: don't know which module to import for autodocumenting u'function_name' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                  
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 1 warning.

Cette ligne semble me dire qu'elle ne connaît pas la fonction

Code :

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

1
2
 
/PATH/index.rst:14: WARNING: don't know which module to import for autodocumenting u'function_name' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)

[Jackbalek]

J'ai trouvé mes erreurs.

Déjà d'une avec l'autofonction je n'avais pas laissé l'automodule.

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
18
19
20
21
22
23
24
 
.. Homework documentation master file, created by
   sphinx-quickstart on Wed Jul 23 09:33:05 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.
 
Welcome to Homework's documentation!
====================================
 
Contents:
 
.. toctree::
   :maxdepth: 2
 
.. automodule:: file_name
 
.. autofunction:: function_name 
 
Indices and tables
==================
 
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Et deuxième erreur que j'avais faite, dans le fichier conf.py j'étais allé trop loin au niveau du path.
J'avais mis :

Code :

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

1
2
 
sys.path.insert(0,"/Path_file/file_name.py")

Alors qu'il fallait mettre:

Code :

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

1
2
 
sys.path.insert(0,"/Path_file/")

Voilà voilà.
J'aurais sûrement d'autres question sur l'architecture de Sphinx, mais pour l'instant cette discussion est résolue.
Merci à tous.