.. include:: special.rst

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

.. code-block:: python

sudo apt-get install python3-sphinx

Ensuite , il suffit d'exécuter la commande suivante pour débuter l'installation de Sphinx

.. code-block :: python

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 :

.. code-block :: python

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 .

.. image:: image/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 .

.. image:: image/root.png

Pour générer les fichiers RST en fichiers HTML depuis le repertoire ``source`` il suffit d'exécuter cette commande :

.. code :: python

make html

.. warning ::
Si vous avez modifié les répertoires par défaut la commande sera :

.. code :: python

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 :

.. image:: image/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

.. image :: image/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 <https://www.sphinx-doc.org/en/master/usage/configuration.html>`_ .

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.

.. warning::
Bien définir le chemin de ce fichier conf.py avec :

.. code-block :: bash

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 .

.. image :: image/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 ::

= - ` : ' " ~ ^ _ * + # < >

.. image :: image/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

.. image :: image/structure.png

Style de texte
______________

Il existe des marqueurs pour pouvoir mettre le texte en **gras** :code:`**gras**` et/ou en *italique* :code:`*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:

.. code :: python

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

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

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 "*":

.. code :: python

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

.. code ::

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:

.. code ::

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é.

.. code ::

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:

.. code ::

.. image:: image/Logo.png

Le résultat:

.. image:: image/Logo.png
:height: 100
:width: 200
:scale: 50

Et pour les gifs :

.. image:: image/nyan-cat-gif-1.gif
:height: 100
:width: 200
:scale: 50

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:

.. code ::

.. image:: Logo.png
:height: 100
:width: 200
:scale: 50
:alt: texte alternatif

Plus d'informations juste `ici <https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/WritingReST/Images.html>`_
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 <https://www.cnam-paysdelaloire.fr/le-mans/le-mans-840946.kjsp>`_

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 : :download:`Le fichier css <download/custom.css>`

Notes, avertissement importantes
________________________________

Si vous voulez mettre en évidence des notes, des avertissements ou des choses importantes, c'est également possible :

.. code ::

.. NOTE::

Ceci est une note.

.. WARNING::

Ceci est un avertissement !

.. IMPORTANT::

Ceci est important !

Ce qui donne :

.. NOTE::

Ceci est une note.

.. WARNING::

Ceci est un avertissement !

.. IMPORTANT::

Ceci est important !

Tableau
_______

Pour ce qui est des tableaux plusieurs manières existent :

.. code ::

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

Ce qui donne :

Ou bien :

.. code ::

.. list-table ::

* - Bonjour
- Au revoir
* - Salut
- Ciao

Qui donne :

.. list-table ::

* - Bonjour
- Au revoir
* - Salut
- Ciao

Code
____

Pour inserer du code dans son texte plusieurs manières existent :

.. code ::

Cette ``manière``

qui donne :

Cette ``manière``

ou alors

.. code ::

Cette :code:`manière`

qui donne :

Cette :code:`manière`

ou encore :

.. code ::

.. code :: (langage)

Cette manière

qui donne

.. code ::

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 :

.. list-table ::

* - 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``

.. image:: image/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 :

.. code :: python

.. automodule:: doc-python
:members:

.. WARNING ::

N'oubliez pas le ``:members:`` sinon votre fonction ne s'affichera pas

.. WARNING ::

Si une erreur vous disant que le module n'a pas été trouvé , écrivez dans le terminal la commande :code:`export PYTHONPATH=votre/chemin/du/repertoire/source`

Plus d'informations juste `ici <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc>`_

Le module toctree
_________________

Il permet de crée des sommaires , comme vous pouvez le voir , l'index est un toctree

.. image :: image/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 :: python

.. 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 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block>`_

.. WARNING ::

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 :

.. code :: python

pip install sphinx-copybutton

Et c'est tout , un bouton copié collé sera disponible ( plus d'informations `ici <https://sphinx-copybutton.readthedocs.io/en/latest/>`_ )

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 :
:download:`Le fichier css <download/custom.css>`
:download:`Le fichier rst <download/special.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

.. WARNING ::

Le fichier ``special.rst`` doit être inclus dans le dossier ``source``

.. WARNING ::

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 : :red:`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

.. code :: bash

pip install sphinx_rtd_theme

Une fois fait dans le fichier ``conf.py`` , il vous faut ajouter :

.. code :: python

html_theme = 'sphinx_rtd_theme'

.. NOTE ::

Le thème possède plusieurs possibilité de modification que vous pouvez retrouver juste `ici <https://sphinx-rtd-theme.readthedocs.io/en/stable/installing.html>`_

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

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``

.. code :: python

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 : :code:`docker pull pardahlman/sphinx`

Ensuite direction les fichier "source" de sphinx , la ou sont situer les documents RST .

Exécuter ensuite la commande : :code:`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 .

.. WARNING::

Cette manière de procèder vous emepechera d'installer des extensions comme ``sphinx-copybutton`` .