Sphinx¶
A quoi sert Sphinx ?¶
Sphinx permet d’écrire un ouvrage technique ou alors de documenter du code . Ici on se concentrera sur comment utiliser Sphinx pour générer une documentation . Pour ce faire , nous utiliserons la syntaxe reStructuredText et nous verrons la manière dont elle s’utilise.
Comment l’installer ? (version Linux)¶
Tout d’abord , pour pouvoir installer Sphinx sous Linux il faut s’assurer d’avoir Python 3 d’installer sur notre ordinateur ( le logiciel Sphinx étant développé sous Python) .
sudo apt-get install python3-sphinx
Ensuite , il suffit d’exécuter la commande suivante pour débuter l’installation de Sphinx
pip install sphinx
Et c’est tout ! Sphinx est installé .
Générer la documentation¶
Maintenant qu’on a vu comment installer Sphinx , on va maintenant voir comment générer une documentation sous Sphinx . Pour ce faire une simple commande existe :
sphinx-quickstart
Suite à l’exécution de cette commande , Sphinx posera plusieurs questions à propos de la création de votre projet . A vous de nommer votre document et d’y inscrire votre nom d’auteur , la date du projet et sa version .

Le répertoire par défaut d’installation sera le répertoire root
. A l’intérieur vous y retrouverez les dossiers source
et build
. Ces dossiers permettent la génération de la documentation .

Pour générer les fichiers RST en fichiers HTML depuis le repertoire source
il suffit d’exécuter cette commande :
make html
Avertissement
Si vous avez modifié les répertoires par défaut la commande sera :
sphinx-build -b html (chemin_répertoire_source) (chemin répertoire_build)
Vous aurez , suite à cela , vos fichiers HTML qui seront générés dans le dossier build
.
Mais , allons plus en profondeur dans la structure des document Sphinx
Structure¶
Dans le dossier source, vous trouverez alors de base quatre éléments.
Le dossier source
¶
Dans ce dossier source se trouve les fichiers les plus importants , c’est à dire :

_static
¶
Le dossier _static
est le dossier par défaut contenant les images qui seront utilisées dans la documentation.
Pour une compatibilité optimale, je vous conseille le format PNG, qui permet entre autres la transparence.
_templates
¶
Ce dossier qui contiendra vos templates supplémentaires si besoin
index.rst
¶
C’est le fichier d’index, votre page de démarrage en quelque sorte. L’extension rst correspond au fichier ReST.
Nous reviendrons sur son fonctionnement, une fois les bases du langage ReST passées en revues

conf.py
¶
Le fichier conf.py
est le fichier contenant toute la configuration du projet de documentation : nom du projet, version, auteur, où trouver les images, log, quelles sont les options activées…
L’ensemble des éléments pouvant être paramétrés sont listés ICI .
Nous allons passer en revue les principaux et plus utiles.
Dans le fichier conf.py
, ils sont presque tous présents, mais commentés. Pour en activer et modifier un, il vous suffit donc de le décommenter.
Avertissement
Bien définir le chemin de ce fichier conf.py avec :
export PYTHONPATH=/chemin/répertoire/source
Le dossier build
¶
Dans ce dossier build , se trouve les fichiers HTML réalisés depuis les fichiers RST insérés dans le dossier source .

_images
¶
C’est à l’intérieur que sont contenus toutes nos images préalablement mit dans notre dossier source
_sources
¶
Contient tout les fichiers RST utilisés reconvertie en fichier texte
_static
¶
Contient tout les éléments graphique dont les fichiers css si nous en avons un
Les fichiers HTML¶
Ce sont les pages générées à partir de nos pages RST via Sphinx
Syntaxe reStructuredText¶
Pour pouvoir rédiger des pages Sphinx , nous devons respecter une certaine syntaxe :
Les titres¶
Pour pouvoir rédiger un titre il suffit de rédiger notre titre et d’y inclure une ligne de l’un de ses caractère
= - ` : ' " ~ ^ _ * + # < >

Structure de texte¶
Pour pouvoir structurer son texte rien de plus simple , il suffit de mettre le même décalage pour les mêmes paragraphes

Style de texte¶
Il existe des marqueurs pour pouvoir mettre le texte en gras **gras**
et/ou en italique *italique*
Si vous voulez faire du code inline comme : code
il vous suffit de mettre ``code``
La syntaxe reStructuredText est assez malin , ce qui fait que l’utilisation de l’un de ces caractères « spéciaux » est totalement possible sans problème .
Cet astérisque * est traité correctement.
Si vous souhaitez par contre *entourer un texte par des astérisques*sans qu’il soit en italique, il est nécessaire d’indiquer que l’astérisque ne doit pas être interprété. Pour cela il suffit de placer une barre oblique inversée juste avant lui, comme ça \*
Listes¶
reStructuredText permet d’utiliser trois types de listes : numérotées , avec puces et de définitions .
Dans chaque cas, nous pouvons avoir autant de paragraphes, sous-listes, etc. que l’on souhaite, tant que le décalage à gauche est aligné sur la première ligne.
Les listes doivent toujours démarrer un nouveau paragraphe , c’est à dire qu’il doit y avoir un saut de ligne juste avant.
Listes numérotées¶
En démarrant une ligne avec un numéro ou une lettre suivie d’un point « . », une parenthèse droite « ) » ou entouré par des parenthèses – comme vous préférez. Toutes ces formes sont reconnues:
1. nombres
A. Lettres en majuscule
qui continue sur plusieurs ligne
avec deux paragraphes et tout !
a. lettres minuscules
3. avec une sous-liste qui démarre à un nombre différent
4. faites attention à garder une séquence de nombre correcte !
I. majuscules en chiffres romains
i. minuscules en chiffres romains
(1) des nombres à nouveau
1) et encore
Le résultat (note : Tous les styles de listes ne sont pas toujours supportés par tous les navigateurs, vous ne verrez donc pas forcément les effets complets) :
nombres
Lettres en majuscule qui continue sur plusieurs ligne
avec deux paragraphes et tout !
lettres minuscules
avec une sous-liste qui démarre à un nombre différent
faites attention à garder une séquence de nombre correcte !
majuscules en chiffres romains
minuscules en chiffres romains
des nombres à nouveau
et encore
Listes à puces¶
De la même manière que pour les listes numérotées, il faut démarrer la première ligne avec une puce – soit « -« , « + » ou « * »:
* une puce "*"
- une sous-liste avec "-"
+ à nouveau une sous-liste
- une autre option
Le résultat :
une puce « * »
une sous-liste avec « -«
à nouveau une sous-liste
une autre option
Listes de définitions¶
Comme les deux autres, les listes de définitions consistent en un terme et la définition de ce terme. Le format est le suivant:
Quoi
Les listes de définitions associent un terme avec une définition.
*Comment*
Le terme est une phrase d'une ligne, et la définition est un
ou plusieurs paragraphes ou éléments, décalés par rapport au terme.
Les lignes vides ne sont pas autorisées entre le terme et la définition
Le résultat :
- Quoi
Les listes de définitions associent un terme avec une définition.
- Comment
Le terme est une phrase d’une ligne, et la définition est d’un ou plusieurs paragraphes ou éléments, décalés par rapport au terme. Les lignes vides ne sont pas autorisées entre le terme et la définition
Préformatage¶
Pour inclure un texte préformaté sans traitement il suffit de terminer le paragraphe par « :: » . Le texte préformaté est terminé lorsqu’une ligne retombre au niveau du décalage précédent.
Par exemple:
Un exemple::
Espaces, nouvelles lignes, lignes vides, et toutes sortes de marqueurs
(comme *ceci* ou \cela) sont préservés dans les bloc préformatés.
Regardez ici, je suis descendu d'un niveau.
(mais pas assez)
Fin de l'exemple
Le résultat:
Un exemple:
Espaces, nouvelles lignes, lignes vides, et toutes sortes de marqueurs
(comme *ceci* ou \cela) sont préservés dans les bloc préformatés.
Regardez ici, je suis descendu d'un niveau.
(mais pas assez)
Fin de l’exemple
Notez que si le paragraphe contient seulement « :: », il est ignoré.
Ceci est un texte préformaté,
le paragraphe "::" est ignoré.
Images et Gif¶
Pour inclure une image dans votre document, vous devez utiliser la directive image
.
Par exemple:
.. image:: image/Logo.png
Le résultat:

Et pour les gifs :

La partie Logo.png
/ nyan-cat-gif-1.gif
indique le chemin d’accès au fichier de l’image qui doit apparaître. Il n’y a pas de restriction sur l’image (format, taille etc). Si l’image doit apparaître en HTML et que vous souhaitez lui ajouter des informations:
.. image:: Logo.png
:height: 100
:width: 200
:scale: 50
:alt: texte alternatif
Plus d’informations juste ici Liens _____
Liens externe¶
Pour faire des liens, c’est aussi simple (notez bien l’espace avant le « < », il est très important) :
`site du CNAM <https://www.cnam-paysdelaloire.fr/le-mans/le-mans-840946.kjsp>`_
Ce qui donne
lien vers le site du CNAM
Liens interne¶
Pour créer un lien qui permet de télécharger un fichier il suffit de mettre la balise :download: :
:download:`Le fichier css <download/custom.css>`
Ce qui donne : Le fichier css
Notes, avertissement importantes¶
Si vous voulez mettre en évidence des notes, des avertissements ou des choses importantes, c’est également possible :
.. NOTE::
Ceci est une note.
.. WARNING::
Ceci est un avertissement !
.. IMPORTANT::
Ceci est important !
Ce qui donne :
Note
Ceci est une note.
Avertissement
Ceci est un avertissement !
Important
Ceci est important !
Tableau¶
Pour ce qui est des tableaux plusieurs manières existent :
+-----------+-----------+-----------+
| Heading 1 | Heading 2 | Heading 3 |
+===========+===========+===========+
| Hello | World | |
+-----------+-----------+-----------+
| foo | |
+-----------+ bar |
| baz | |
+-----------+-----------------------+
Ce qui donne :
Heading 1
Heading 2
Heading 3
Hello
World
foo
bar
baz
Ou bien :
.. list-table ::
* - Bonjour
- Au revoir
* - Salut
- Ciao
Qui donne :
Bonjour
Au revoir
Salut
Ciao
Code¶
Pour inserer du code dans son texte plusieurs manières existent :
Cette ``manière``
qui donne :
Cette manière
ou alors
Cette :code:`manière`
qui donne :
Cette manière
ou encore :
.. code :: (langage)
Cette manière
qui donne
Cette manière
Expression mathématiques¶
Le module pngmath vous permet de saisir des formules mathématiques, au format LaTeX, et de les afficher sous la forme d’images. La directive est « math ».
Voici la syntaxe LaTeX :
Désignation mathématique |
Écriture LaTeX |
Puissance |
a^2 |
Indice |
a_2 |
Mix |
a^{2}_{3} |
Fraction |
\frac{numerateur}{denominateur} |
Racine carrée |
\sqrt[puissance]{valeur} |
Sinus , cosinus , tangente |
\sin, \cos, \tan, \arcsin, \arccos, \arctan |
Somme |
\sum_{valeur inferieure}^{valeur superieure} |
Intégrale |
\int_{valeur inferieure}^{valeur superieure} |
Infini |
\infty |
Pi |
\pi |
Inclure des fonctions via python¶
Sphinx a la possibilité de documenter vos documents Python très facilement :
Tout d’abord ajouter l’extension `sphinx.ext.autodoc`
à votre dossier conf.py

Ensuite , ajouter votre code python dans un fichier python qui sera dans le dossier source
Dans votre fichier RST , rajouter le modulte automodule
comme cela :
.. automodule:: doc-python
:members:
Avertissement
N’oubliez pas le :members:
sinon votre fonction ne s’affichera pas
Avertissement
Si une erreur vous disant que le module n’a pas été trouvé , écrivez dans le terminal la commande export PYTHONPATH=votre/chemin/du/repertoire/source
Plus d’informations juste ici
Le module toctree¶
Il permet de crée des sommaires , comme vous pouvez le voir , l’index est un toctree

Ici , l’option :maxdepth: 2
signifie qu’il ne peut y a voir que 2 titres d’afficher ( titre et sous-titre )
L’option :caption:
quant à elle permet de donner un nom à notre toctree ici Sommaire
Le module code-block¶
Le module code-block comme vu précédemment permet d’inclure du code dans notre page Sphinx , mais celui-ci possède des attributs qui peuvent être activé ou non.
Pour ajouter un attribut cela se passe comme cela :
.. code-block :: (langage)
:attribut:
Code blabla
Les attribut les plus important sont :
linenos
qui permet de rajouter les numéros de ligne sur le cotécaption
qui permet de rajouter un titre à notre block de code
D’autre attribut exisent , vous pouvez les retrouvez juste ici
Avertissement
L’extension copy-button vue juste en dessous entre en conflit avec l’attribut linenos. En effet , le bouton copié copieras aussi les chiffres des lignes .
Personnaliser son site Sphinx :¶
Sphinx possède un large panel de modification possible , la mise en forme d’une page est très importante pour la différencier des autres
Bouton Copie-Colle pour les lignes de codes¶
Il est possible d’inclure un bouton copié collé pour nos lignes de codes comme le fait cette documentation Sphinx . Pour se faire , il suffit de rajouter l’extenstion sphinx_copybutton dans notre fichier conf.py et de saisir la commande :
pip install sphinx-copybutton
Et c’est tout , un bouton copié collé sera disponible ( plus d’informations ici )
Texte en couleur¶
Inclure des couleurs dans son texte Sphinx est un peu plus compliqué , il va nous falloir 2 fichiers et rajouter une ligne dans le fichier conf.py
:
- Tout d’abord commençons par les deux fichier :
Ces deux fichiers sont essentiels , ils nous permettent d’inclure la couleur à notre page
Note
N’oubliez pas de rajouter la ligne .. include:: special.rst
au début de chacun de vos fichiers RST pour utiliser les couleurs
Note
la ligne de commande html_css_files = ["custom.css"]
doit être incluse dans le fichier conf.py
Avertissement
Le fichier special.rst
doit être inclus dans le dossier source
Avertissement
Le fichier custom.css
doit être inclus dans le dossier _static
du dossier source
Une fois cela fait , dans votre fichier RST , il ne vous reste qu’à faire ceci pour écrire en couleur : :red:`couleur`
, ce qui donne : couleur
Note
red est associé à la couleur rouge , à vous de la modifié selon la couleur que vous souhaitez , en anglais .
Modifier son thème¶
Comme vous l’avez peut-être remarqué , Sphinx met à votre disposition différents thèmes , celui par défaut est le thème dit classique le thème utilisé ici ( et aussi le + utilisé ) est le thème RTD . Certes moins personnalisable que le thème par défaut , le thème RTD propose une clarté et une organisation nettement supérieur à celui du thème classique .
L’installation de chaque thème est propre à chacun mais je vais vous montrer l’exemple avec le thème RTD.
Tout d’abord il faut télécharger le thème sur le net
pip install sphinx_rtd_theme
Une fois fait dans le fichier conf.py
, il vous faut ajouter :
html_theme = 'sphinx_rtd_theme'
Note
Le thème possède plusieurs possibilité de modification que vous pouvez retrouver juste ici
Modifier la couleur des texte inline
¶
Les codes ìnline
possèdent par défaut une couleur rouge et un fond blanc , mais il existe un moyen de la modifier tout ca via le fichier custom.css
il suffit d’inclure la ligne suivante :
code.literal {
color: #404040 !important;
background-color: #fbfbfb !important;
}
L’attribut
color
modifie la couleur du texteL’attribut
background-color
modifie le fond
Modifier le logo et l’icone¶
Pour modifier l’icone du site et son logo , il vous faut tout d’abord inclure les images du logo et de l’icone dans le dossier _static
Une fois fait il suffit d’ajouter ces deux lignes au fichier conf.py
html_favicon = "Nom_De_Icone.ico"
html_logo = "Nom_Du_Logo.jpg"
Sphinx avec Docker¶
Il existe une manière beaucoup plus pratique d’utiliser Sphinx : L’utilisez dans un contenaire Docker !
Cela vous permettra plutôt que d’éviter de passez par plusieurs commandes de mettre a jour vos différents fichiers Sphinx en ne modifiant que le fichier dans le document source .
Pour ce faire nous réutilissons une image Docker qui est pardahlman/sphinx
Nous commençons par récuperer l’image docker : docker pull pardahlman/sphinx
Ensuite direction les fichier « source » de sphinx , la ou sont situer les documents RST .
Exécuter ensuite la commande : docker run -d -v .:/docs -p 8000:8000 pardahlman/sphinx
Une fois cela fait rendez-vous sur internet et sur http://localhost:8000/
Vous aurez directement votre documentation Sphinx . Lorsque vous effectuerez une modification sur les fichiers source
elle s’effectueras automatiquement sur la version web .
Important
Veillez à ce que le thème de votre Sphinx soit bien renseignez dans le fichier config.py
de vos ressources sphinx .
Avertissement
Cette manière de procèder vous emepechera d’installer des extensions comme sphinx-copybutton
.