{{tag>dev python sphinx documentation}}


====== sphinx : Générateur de documentation =====

Sphinx est un programme dédié à la génération de tous types de documentation associée à un projet:
  * La documentation de référence (documentation des modules, classes et APIs);
  * les tutoriaux (documentation à objectifs pédagogiques);
  * Les How-To (documentation ayant pour objet la résolution de problèmes);
  * Les documents explicatifs ayant pour objectif de faire connaître ou de justifier certains choix.

Souvent on pense à Sphinx comme à un outil de génération de documentation technique pour Python capable d'extraire les docstrings du code afin de produire une documentation de référence en HTML.

Plus généralement Sphinx peut prendre en entrée tout type de document texte et produire une sortie lisible.

En général les fichiers texte en entrées utilisent le formatage **reStructredText** et la sortie produite par Sphinx est un ensemble de documents formatés en HTML.

  * Sphinx propose d'autres types de sorties comme PDF, ePub, man etc.
  * Sphinx a besoin d'un fichier de configuration (conf.py)
  * Sphinx est modulaire, il comporte de nombreuses extensions facilement activables.


===== Installer Sphinx et le theme Read The Doc =====


===== Ajouter des pages =====

  * Créer un fichier .rst dans le dossier de la documentation ;
  * Référencer la nouvelle page dans l'index.

<note>
  * La page doit contenir au moins un titre pour être utilisée par Sphinx.
  * Laisser une ligne vide sous les paramètres de la directive ''toctree::'' et respecter l'indentation en s'alignant sous les paramètres.
</note>

<code python>
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   ./maNouvellePage.rst
</code>

===== reStructuredText =====

La syntaxe reStructuredText, bien que proche de Markdown, est plus complète mais également plus stricte.

Pour l'essentiel :
<code>
Voici du texte en *italique*, en **gras**, et voici du ``code inline`` composant un premier paragraphe.

Ce second paragraphe est séparé du premier par une ligne vide.
</code>



  * Le site officiel de Sphinx propose une [[https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html|introduction plus complète à reStructuredText]]
  * Confère également la [[https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title|documentation en ligne des directives reStructuredTest]]


===== Auto-documenter un package Python =====

Sphinx a été conçu par la communauté Python pour les projets Python. Cependant il est utilisés par de nombreux autres projets opensource.

Sphinx utilise l'extension **autodoc** pour inclure les docstrings dans la documentation à produire.

reStructuredText est le formatage utilisé par défaut mais d'autre formatages peuvent être utilisés comme Markdown mais dans ce cas des extensions supplémentaires seront nécessaires.

Pour documenter l'ensemble des classes d'un module:
  * Le fichier conf.py doit avoir l'extension autodoc (''sphinx.ext.autodoc'') déclarée;
  * Le fichier RST doit utiliser la directive automodule avec l'option '':members:''

<code rst>
.. automodule:: my_module_name
   :members:
</code>


===== L'extension doctest =====

''sphinx.ext.doctest''
===== Références =====

  * https://www.youtube.com/watch?v=tXWscUSYdBs
  * https://towardsdatascience.com/documenting-python-code-with-sphinx-554e1d6c4f6d?gi=87fa36d74a8f
  * https://stackoverflow.com/questions/9534513/how-to-document-python-function-parameters-with-sphinx
  * https://riptutorial.com/python-sphinx/example/26112/adding-your-code-path-in-the-sphinx-config