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
1. avec une sous-liste qui démarre à un nombre différent
2. 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 :: Le fichier css Le fichier rst

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 texte
L’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 .

Sphinx¶

A quoi sert Sphinx ?¶

Comment l’installer ? (version Linux)¶

Générer la documentation¶

Structure¶

Le dossier source¶

_static¶

_templates¶

index.rst¶

conf.py¶

Le dossier build¶

_images¶

_sources¶

_static¶

Les fichiers HTML¶

Syntaxe reStructuredText¶

Les titres¶

Structure de texte¶

Style de texte¶

Listes¶

Listes numérotées¶

Listes à puces¶

Listes de définitions¶

Préformatage¶

Images et Gif¶

Liens externe¶

Liens interne¶

Notes, avertissement importantes¶

Tableau¶

Code¶

Expression mathématiques¶

Inclure des fonctions via python¶

Le module toctree¶

Le module code-block¶

Personnaliser son site Sphinx :¶

Bouton Copie-Colle pour les lignes de codes¶

Texte en couleur¶

Modifier son thème¶

Modifier la couleur des texte inline¶

Modifier le logo et l’icone¶

Sphinx avec Docker¶

Le dossier `source`¶

`_static`¶

`_templates`¶

`index.rst`¶

`conf.py`¶

Le dossier `build`¶

`_images`¶

`_sources`¶

`_static`¶

Modifier la couleur des texte `inline`¶