Skip to content

GitLab

Commit 51a7af27 authored by CHAMONT David's avatar CHAMONT David
Browse files

Reorganisation des tutos

parent d67b72bf
Hide whitespace changes
Inline Side-by-side
Showing with 0 additions and 559 deletions
Sphinx-doc/README.md deleted 100644 → 0
View file @ d67b72bf
# Sphinx : un outil de génération de documentations
Sphinx est l'outil *open source* officiel de la communauté Python pour générer les documentations techniques.
S'appuyant sur le langage *reStructuredText* (ReST), il permet de générer à partir d'un même source des documents
dans un grand nombre de formats (HTML, PDF, man, …).
Ce plongeon montre comment créer une documentation au format HTML avec Sphinx.
* prérequis : aucun
* hauteur du plongeoir : 0.5m
* préinstallation : Docker, image `piscineri3/sphinx-doc:1.0`
* fichiers : https://gitlab.in2p3.fr/MaitresNageurs/PiscineJI/tree/master/Sphinx-doc
* maître(s) nageur(s) : [Antoine Pérus](http://informatique.in2p3.fr/?q=user/21)
---
## Vérification de l'environnement de travail
Vous modifierez vos fichiers de travail au sein du système
d'exploitation natif de votre ordinateur portable, avec vos outils d'édition
habituels, et utiliserez une machine Docker uniquement pour générer la documentation.
Vous devriez avoir déjà installé Docker et, éventuellement VirtualBox, conformément aux instructions
du [README.md](../README.md) principal de ce projet. Pour vérifier que votre Docker
est opérationnel, ouvrez une fenêtre de commande et tapez `docker run hello-world` :
$> docker run --rm hello-world
Hello from Docker!
This message shows that your installation appears to be working correctly.
To generate this message, Docker took the following steps:
1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
3. The Docker daemon created a new container from that image which runs the
executable that produces the output you are currently reading.
4. The Docker daemon streamed that output to the Docker client, which sent it
to your terminal.
To try something more ambitious, you can run an Ubuntu container with:
$ docker run -it ubuntu bash
Share images, automate workflows, and more with a free Docker Hub account:
https://hub.docker.com
For more examples and ideas, visit:
https://docs.docker.com/engine/userguide/
Vous devriez également déjà disposer de l'image `piscineri3/sphinx-doc:1.0`. Si ce n'est pas
le cas et que vous disposez de réseau, tapez `docker pull piscineri3/sphinx-doc:1.0`.
Vous éditerez vos fichiers dans le répertoire local <LOCAL>, et vous monterez ce répertoire en tant que
`/home` au sein de la machine Docker.
À présent, testez votre container Docker `piscineri3/sphinx-doc:1.0` :
$> docker run --rm -it -v <LOCAL>:/home piscineri3/sphinx-doc:1.0 /bin/sh
/ # cd /home
/home # sphinx-quickstart --version
Sphinx v1.4.5
Vous êtes prêt.
---
## Générer une documentation avec Sphinx
### Mise en place
Pour créer une nouvelle documentation, on se place dans le dossier qui va contenir l'ensemble de la documentation et on exécute
la commande ```sphinx-quickstart```. Par défaut, celle-ci travaille en mode interactif en posant de nombreuses questions qui
permettent de paramétrer la génération de la documentation. Il est également possible d'utiliser ```sphinx-quickstart```
en mode *batch*, comme ici (voir le fichier [create.sh](create.sh)) :
/home # sphinx-quickstart --quiet \
--sep \
--project='Piscine JI-2016' \
--author='Moi' \
-v '0.1.0' \
--language='fr' \
--no-batchfile \
.
Ici, `sphinx` va préparer le projet de documentation en séparant les fichiers sources (dans le dossier `source`) des fichiers
générés (dans le dossier `build`); on a spécifié - c'est obligatoire - un titre général, un auteur et une version; par ailleurs,
on a également paramétré la langue utilisée pour l'interface, on a précisé qu'on n'utiliserait pas de fichier `make.bat`
puisqu'on va travailler sous Linux via Docker. Noter le `.` final du dossier courant …
Les différentes options de la commande ```sphinx-quickstart``` sont détaillées ici : [Sphinx documentation - Invocation of sphinx-quickstart](http://www.sphinx-doc.org/en/stable/invocation.html)
L'ensemble généré doit être le suivant :
.
├── Makefile
├── build
└── source
├── _static
├── _templates
├── conf.py
└── index.rst
#### [**Exo**] Générer dès maintenant un embryon de documentation fonctionnel :
/home # make html
La documentation générée est mise dans un ensemble complètement autonome, dans le dossier `build/html`,
le point d'entrée étant `./build/html/index.html` :
.
├── Makefile
├── build
│   ├── doctrees
│   │   ├── environment.pickle
│   │   └── index.doctree
│   └── html
│   ├── _sources
│   ├── _static
│   ├── genindex.html
│   ├── index.html
│   ├── objects.inv
│   ├── search.html
│   └── searchindex.js
└── source
├── _static
├── _templates
├── conf.py
└── index.rst
#### [**Exo**] Vérifier qu'on obtient bien, en ouvrant le fichier `index.html` dans son butineur préféré (directement sur la machine hôte) :
![Doc - V1](Images/doc-1.png "Doc - V1")
#### [**Exo**] Vérifier qu'en déplaçant le dossier `build/html`, en le renommant éventuellement et en ouvrant le fichier `index.html`, on conserve une documentation complète, autonome et fonctionnelle.
----
### Éditions de base
#### Configuration
Le fichier `conf.py` permet de gérer la configuration via la définition ou la déclaration de paramètres, dont un certain nombre
ont été initialisés à la création du projet avec `sphinx-quickstart`. C'est un fichier Python pouvant contenir toute expression
en python …
Remarque : lorsqu'on édite le fichier de configuration `source/conf.py`, la prise en compte des modifications peut nécessiter
une reconstruction complète :
/home # make clean && make html
#### [**Exo**] Changer le thème d'affichage par défaut `alabaster` pour le thème `agogo`; on doit obtenir :
![Doc - V2](Images/doc-2.png "Doc - V2")
#### [**Exo**] Changer le titre du bandeau pour un plus sobre "Piscine JI-2016" et rajouter un logo (récupérer l'image [ici](./Images/ccri3-50.png)_ en la rangeant dans le répertoire `_static`)
![Doc - V3](Images/doc-3.png "Doc - V3")
La gestion des différents paramètres du fichier de configuration est détaillée ici :
[Sphinx documentation - The build configuration file](http://www.sphinx-doc.org/en/stable/config.html#module-conf)
Les différents thèmes disponibles en standard avec Sphinx sont décrits ici :
[Sphinx documentation - HTML theming support](http://www.sphinx-doc.org/en/stable/theming.html#builtin-themes)
#### Contenu
Le contenu de notre projet de documentation sera exclusivement fourni sous forme de fichiers textuels, par défaut au format *reStructuredText*, et avec pour point d'entrée le fichier `index.rst`. Le choix du suffixe est défini dans le fichier `conf.py`.
#### [**Exo**] Franciser le contenu généré par `sphinx-quickstart`, supprimer la référence aux modules (qu'on n'utilisera pas ici) et rajouter un paragraphe d'introduction pour obtenir ceci :
![Doc - V4](Images/doc-4.png "Doc - V4")
On fait apparaître un texte en gras en l'encadrant par \*\* (\*\*mot\*\* en **gras**) et en italique en l'encadrant
par \* (\*mot\* en *italique*).
----
### Édition
Pour étoffer notre documentation, nous allons l'enrichir en ajoutant 2 fichiers. Ces derniers doivent être référencés
explicitement dans le fichier `index.rst`, sous la directive `toctree`.
#### [**Exo**] Créer 2 fichiers `intro.rst` et `exemple.rst` dans le répertoire `source`
Ces 2 fichiers doivent obligatoirement avoir en tête un titre, par exemple :
```
============
Introduction
============
```
et
```
========
Exemples
========
```
En ReST, les titres sont soulignés d'un caractère spécial indiquant leur niveau. Un même titre doit systématiquement être souligné
du même caractère. Il doit y avoir autant de caractères spéciaux que de caractères dans le titre. Le changement de caractère induit
le passage à un sous-niveau de titre. Les caractères utilisés sont, entre autres : `*`, `=`, `+`,`~`, `-`
Le titre de page peut être souligné et surligné de son caractère spécial.
#### [**Exo**] Ajouter la référence aux 2 fichiers qu'on vient de créer dans l'index (fichier `source/index.rst`) en utilisant la directive `doctree` :
```
.. doctree::
:caption: Sommaire :
:maxdepth: 1
intro
exemple
```
Le fonctionnement des *directives* repose sur le même principe que les blocs de code en Python : l'indentation.
Pour ReST les trois premiers caractères d'une ligne sont significatifs :
* s'il s'agit de texte simple, on commence à écrire dès le début de la ligne (pour un bloc donné)
* une directive commence toujours par 2 points suivis d'un espace
* le texte rattaché à une directive est décalé de 3 espaces; tant q'on respecte ces trois espaces, on reste dans le bloc
Une directive a donc la forme suivante :
```
<ligne vide>
.. <nom>:: <arguments>
:<options: <valeur>
<ligne vide éventuelle, parfois obligatoire>
<le texte associé>
```
Les directives et leurs options (facultatives) doivent être collées (pas de ligne vide de séparation), mais doivent être
séparées par des lignes vides de toute autre directive ou texte. C'est vrai également pour les titres et les listes.
On doit maintenant obtenir ceci :
![Doc - V5](Images/doc-5.png "Doc - V5")
#### [**Exo**] Rajouter, dans `source/intro.rst`, le texte d'introduction avec les liens tel que présenté ci-après :
![Doc - V6](Images/doc-6.png "Doc - V6")
Il y a plusieurs façons de traiter les liens en ReST; les 2 plus courantes sans doute sont, sous forme d'exemples :
1. la forme 'standard'
```
External hyperlinks, like Python_.
.. _Python: http://www.python.org/
```
2. une forme 'intégrée'
```
External hyperlinks, like `Python <http://www.python.org>`_.
```
Enfin, les blocs de listes sont précédés et suivis d'une ligne blanche, chaque item commençant, de façon homogène,
par un caractère `-`, `*` ou `+`. Les blocs définissant une sous-liste seront indentés de 3 caractères et précédés
d'une ligne blanche.
Les liens à rajouter :
http://www.sphinx-doc.org/en/stable/invocation.html
http://www.sphinx-doc.org/en/stable/config.html#module-conf
http://www.sphinx-doc.org/en/stable/theming.html#builtin-themes
http://pygments.org/docs/lexers/
#### [**Exo**] Rajouter, dans `source/exemple.rst`, l'image du plongeon illustrant cet atelier
![Doc - V7](Images/doc-7.png "Doc - V7")
Voici un exemple de directive permettant d'ajouter une image, centrée dans son paragraphe et réduite de 50% :
.. image:: path/to/image.png
:scale: 50%
:align: right
#### [**Exo**] Rajouter des tableaux :
Il y a plusieurs façons de saisir un tableau en ReST :
* 'simple'
```
===== ===== ======
H0 H1
------------ ------
H01 H02 H11
===== ===== ======
r1 r2 r3
r4 r5 r6
===== ===== ======
```
* 'un peu moins simple' …
```
+-----+-----------+
| H0 | H1 |
+=====+=====+=====+
| r0 | r1 | r2 |
+-----+-----+-----+
```
* avec un format 'csv'
```
.. csv-table:: csv-table
:header: Nom, Prénom
:widths: 150, 50
Leroy, Arthur
Mari, Pierre
```
* à partir de listes
```
.. list-table:: list-table
:widths: 50 30 20
:header-rows: 1
:stub-columns: 1
* - Nom
- Prénom
- Age
* - Leroy
- Arthur
- 99
```
Rajouter, dans `source/exemple.rst`, les tableaux suivants en utilisant les différents formats présentés ci-dessus :
![Doc - V8](Images/doc-8.png "Doc - V8")
#### [**Exo**] Rajouter, toujours dans `source/exemple.rst`, la formule mathématique suivante :
![Doc - V9](Images/doc-9.png "Doc - V9")
Rajouter l'utilisation de l'extension `'sphinx.ext.mathjax'` dans le fichier de configuration `source/conf.py`
et utiliser la directive `math` avec l'expression ``` x = {-b \pm \sqrt{b^2-4ac} \over 2a} ``` pour afficher
la formule mathématique.
En fait, l'expression mathématique ne sera affichée graphiquement que si l'accès à la librairie `MathJax`
est possible via le réseau, à défaut de l'avoir installée localement. En l'absence de réseau ou bien pour
minimiser le trafic, il est possible d'utiliser une librairie `MathJax` locale :
* Récupérer l'archive `MathJax.zip`, la décompresser dans son répertoire de travail <LOCAL>
* Rajouter dans le fichier de configuration `conf.py`, le chemin d'accès absolu à la bibliothèque :
mathjax_path = '/\<LOCAL\>/MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
* Reconstruire et tester :
/home # make clean && make html
On trouvera des exemples d'utilisation de MathJax : [ici](http://cdn.mathjax.org/mathjax/latest/test/examples.html)
('`Ctl-click/Show Math As/Tex commands`' sur les formules pour voir le source)
#### [**Exo**] Lien interne
Le texte vers lequel on veut pointer est référencé par un label suivi d'une ligne blanche :
````
.. _label:
````
En Sphinx, on référence le label de la manière suivante :
````
:ref:`le texte <label>`
````
Rajouter en 1e page (`index.rst`) un lien pointant directement vers la formule mathématique de l'exercice précédent :
![Doc - V10](Images/doc-10.png "Doc - V10")
#### [**Exo**] Extraits de codes
La directive Sphinx permettant d'afficher des bouts de codes est la suivante :
````
.. code-block:: <langage>
````
le langage étant l'un de ceux gérés par *Pygments*. Cette directive connaît plusieurs options, dont :
* :linenos: : pour numéroter ou non les lignes du bloc de code
* :emphasize-lines: n[,m-p] : pour surligner certaines lignes de code
Rajouter le bloc de code suivant en surlignant les lignes 1 et 4 à 5 :
````
def some_function():
interesting = True
print 'This line is highlighted.'
print 'This one is not …'
print '… but this one is.'
````
![Doc - V11](Images/doc-11.png "Doc - V11")
----
### Quelques subtilités Sphinx/ReST
Pour pouvoir utiliser une feuille de style propre au projet, par exemple `custom.css`,
éditer `source/conf.py` et rajouter avant la section `HTML output` :
````python
def setup(app):
app.add_stylesheet('custom.css')
````
#### [**Exo**] Modifier le style d'un élément
Par exemple, on veut afficher les en-têtes de tableaux en rouge …
* rajouter le fichier `source/_static/custom.css` :
````css
thead {
color: red;
text-align: center;
}
````
* reconstruire :
/home # make clean && make html
![Doc - V12](Images/doc-12.png "Doc - V12")
#### [**Exo**] Ajouter un élément de style
Par exemple, on veut pouvoir distinguer un groupe de mot, en créant un nouveau `role` …
* en tête de fichier source, rajouter :
.. role:: brown
* puis, dans le même fichier source, utiliser ce nouveau `role`, par exemple en 'décorant' l'âge dans le tableau 'list-table' :
````
:brown:`99`
:brown:`20`
:brown:`59`
````
* reconstruire :
/home # make clean && make html
![Doc - V13](Images/doc-13.png "Doc - V13")
#### [**Exo**] Ajouter un attribut à un élément de style
Par exemple, on peut enrichir une directive avec un attribut `pseudocode` …
* dans le fichier `source/exemple.rst` rajouter :
````
.. pseudocode::
::
try:
statements to be executed inside try clause
statement2
statement3
...
except ExceptionName:
statements to be evaluated in case of ExceptionName happens
else:
statements to be evaluated in case of no exception happens
finally:
statements to cleanup in any cases
````
![Doc - V14](Images/doc-14.png "Doc - V14")
* rajouter le fichier `source/_static/custom.css` :
````css
div.pseudocode {
font-style: italic;
color: blue;
}
````
* reconstruire :
/home # make clean && make html
----
### Quelques remarques
Dans ce plongeon nous avons généré la documentation sous la forme d'un dossier autoconsistant avec des fichiers au format HTML.
Sphinx permet de créer cette même documentation sous d'autres formats. L'image docker utilisée pour ce plongeon ne contient pas
les packages externes nécessaires pour générer des documents LateX et PDF pour des raisons de taille de ces packages externes
et donc, vous ne pourrez pas, ici, tester les cibles `latex` et `latexpdf` par exemple; mais sachez que ça marche bien !
Par contre vous pouvez tester la cible `singlehtml` qui permet de générer la documentation dans un seul fichier HTML.
Notez également que la cible `dummy` permet de valider ses sources au format *reStructuredText* et que la cible `linkcheck`
permet de tester les liens de la documentation :
/home # make clean && make singlehtml
/home # make clean && make dummy
/home # make clean && make linkcheck
---
## Questionnaire
Merci d'envoyer quelques commentaires à l'auteur :
* Environnement de travail opérationnel ? oui [ ], non [ ]
* Vous aviez les pre-requis ? oui [ ], non [ ]
* Comment jugez-vous la difficulté du plongeon ? trop simple [ ], adapté [ ], trop compliqué [ ]
* Durée du plongeon ? trop court [ ], 15-20 minutes [ ], trop long [ ]
* Pourquoi avez-vous choisi ce plongeon ? :
* Signalement de typos, erreurs, etc :
* Commentaires libres :
---
## Liens
* [Sphinx documentation](http://www.sphinx-doc.org/en/stable/index.html)
* [Installing Sphinx](http://www.sphinx-doc.org/en/stable/install.html)
* [Pygments - Available lexers](http://pygments.org/docs/lexers/)
Enfin, deux (*bonnes*) références pour se familiariser avec la syntaxe *ReST* et son utilisation dans *Sphinx* :
* [Sphinx - reStructuredText Primer](http://www.sphinx-doc.org/en/stable/rest.html)
* [Sphinx/Rest Memo](http://rest-sphinx-memo.readthedocs.io/en/latest/index.html)
---
© *CNRS 2016*
*Assemblé et rédigé par Antoine Pérus, cette œuvre est mise à disposition selon les termes de la*
*[Licence Creative Commons - Attribution - Pas d’Utilisation Commerciale - Partage dans les Mêmes Conditions 4.0 International](http://creativecommons.org/licenses/by-nc-sa/4.0/)*
Sphinx-doc/create.sh deleted 100755 → 0
View file @ d67b72bf
#!/usr/bin/env sh
#
# Creation du projet de documentation pour l'outil Sphinx
#
# Cf. : http://www.sphinx-doc.org/en/stable/invocation.html
sphinx-quickstart --quiet \
--sep \
--project='Piscine JI-2016' \
--author='Moi' \
-v '0.1.0' \
--language='fr' \
--no-batchfile \
.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment