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 .

_images/Quick1.png

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 .

_images/root.png

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 :

_images/source.png

_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

_images/index.png

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/build.png

_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

= - ` : ' " ~ ^ _ * + # < >
_images/Titre.png

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

_images/structure.png

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

  1. nombres

  1. Lettres en majuscule qui continue sur plusieurs ligne

    avec deux paragraphes et tout !

  1. lettres minuscules

    1. avec une sous-liste qui démarre à un nombre différent

    2. faites attention à garder une séquence de nombre correcte !

  1. majuscules en chiffres romains

  1. minuscules en chiffres romains

  1. des nombres à nouveau

  1. 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:

_images/Logo.png

Et pour les gifs :

_images/nyan-cat-gif-1.gif

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

_images/conf.png

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

_images/toctree.png

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 .