Sphinx est un programme dédié à la génération de tout type de documentation associée à un projet:

• La documentation de référence du code (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 documents textes et produire une sortie parmi un ensemble de formats 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.

# Création d'un environnement virtuel Python
python3 -m venv env
 
# Activer l'environnement
source env/bin/activate
 
# Installation de Sphinx
pip install sphinx

Sphinx a besoin d'une arborescence spécifique pour fonctionner. La commande sphinx-quickstart est interactive et se charge de créer ces répertoires et fichiers.

Par défaut la commande crée un dossier nommée source pour accueillir la documentation. Pour éviter toute confusion surtout si Sphinx est utilisé pour documenter un projet de code, on peut sans problème renommer ce dossier :

mv source doc

Une fois le dossier renommé, il faut modifier la valeur de la variable SOURCEDIR du Makefile et de make.bat.

Pour valider l'installation et les paramétrages initiaux, on tente de générer la documentation :

# Générer la documentation
make html
 
# Consulter la documentation produite
firefox build/html/index.html

Sphinx utilise par défaut le theme minimaliste Alabaster, un thème plus complet et populaire est disponible via pip :

pip install sphinx-rtd-theme

Pour remplacer le thème par défaut, éditer docs/conf.py et remplacer la valeur de la variable html_theme :

html_theme = 'sphinx_rtd_theme'

Les thèmes sont configurables. Confère la documentation du thème Read The Docs.

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

hello.rst

Hello World
===========
 
Hello Sphinx !!!

Le fichier index.rst a le contenu suivant

.. toctree::
   :maxdepth: 2
   :caption: Contents:
 
   ./hello.rst

La directive toctree permet de générer la table des matières (table of content).

• Le paramètre :maxdepth: spécifie le nombre de niveaux de titres à afficher dans la table. Avec une valeur 1 seul les titres de page seront présents dans l'index.
• Le paramètre :caption: permet de définir le titre à afficher au dessus du sommaire ;
• Attention a bien laisser la ligne vide qui sépare les paramètres de la directive de son contenu.

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

Pour l'essentiel :

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.

Pour les titres :

Titre principal
===============


Titre de niveau 2
-----------------


Titre de niveau 3
~~~~~~~~~~~~~~~~~

On définit un niveau de titre en le surlignant avec les caractères spéciaux. Par défaut, les niveaux de titres ne sont pas associés à un caractère particulier, c'est l'ordre d'usage qui permet à Sphinx de déterminer le niveau de titre.

Par convention dans le guide de la documentation du code en Python on trouve :

• # pour les parties
• * pour les chapitres
• = pour les sections
• - pour les sous-sections
• ^ pour les sous-sous-sections
• “ pour les paragraphes

Pour une URL (externe) :

Syntaxe d'écrite d'une URL `mon titre <https://example.com>`_

• Attention aux guillemets arrières ;
• Attention à l'espace avant < ;
• Attention à l'underscore;

Les listes :

Liste à puce :

* Ceci est une liste
* un autre élément

  * Une sous-liste
  * Notez bien le saut de ligne avec la liste principale,
    ça ne marchera pas si vous l'oubliez !
    Ce même élément s'étend sur 3 lignes.

* un dernier élément

Liste ordonnée :

1. Un
2. Deux
3. Trois

Une autre liste ordonnée :

#. Un
#. Deux
#. Trois

Blocs de code

Voici comment faire un bloc que code simple ::

   Ceci est un bloc de code. Il est créé grâce aux doubles deux-points.

On peut également placer les doubles deux-points seuls si on ne veut pas
terminer sa phrase par ce symbole.

::

   Voici un autre bloc de code...

Et c'est pas fini ! On peut aussi définir un bloc de code avec une syntaxe
plus explicite, grâce à laquelle on peut indiquer à Sphinx dans quel
langage il est rédigé, ce qui lui permettra d'activer la coloration
syntaxique :

.. code-block:: python

   #!/usr/bin/env python

   print("Ceci est un bloc de code Python\n")

On change l'indentation pour sortir du bloc de code.

On peut également utiliser des blocs

.. NOTE::

   Ceci est une note.

.. WARNING::

   Ceci est un avertissement !

.. IMPORTANT::

   Ceci est important !

• Le site officiel de Sphinx propose une introduction plus complète à reStructuredText
• Confère également la documentation en ligne des directives reStructuredTest

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:

.. automodule:: my_module_name
   :members:

Introduire les images (png, jpg, gif)

Voici une image :

.. figure:: ./images/image.png

Voici un autre image avec quelques paramètres en plus :

.. figure:: ./images/image.png
   :alt: Texte alternatif
   :target: https://example.com/
   :width: 400px
   :align: center

   Texte affiché sous l'image (même indentation)

Pour les tableaux, on définit les cellules telles qu'on souhaite les voir s'afficher :

+-----------+-----------+-----------+
| Heading 1 | Heading 2 | Heading 3 |
+===========+===========+===========+
| Hello     | World     |           |
+-----------+-----------+-----------+
| foo       |                       |
+-----------+          bar          |
| baz       |                       |
+-----------+-----------------------+

En plus de la syntaxe propre à reStructuredTest, Sphinx introduit des éléments spécifiques à la documentation du code

sphinx.ext.doctest

• 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
• https://blog.flozz.fr/2020/09/07/introduction-a-sphinx-un-outil-de-documentation-puissant/