Doc Sphinx et script python

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:

---

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.

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:

---

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:

---

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

---

du fichier de config.

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 ?

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.

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

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

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

Cette fonction autofunction semble pas mal du tout :).

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

Code:

---

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:

---

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:

---

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)

---

J'ai trouvé mes erreurs.

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

Code:

---

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:

---

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

---

Alors qu'il fallait mettre:

Code:

---

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.