---
myst:
html_meta:
keywords: sphinx,compilation,local
---
# Compilation en local de la FAQ
Pour voir les effets des modifications qu'ils ont apportées aux fichiers sources
`.md` de la FAQ, les contributeurs doivent *a priori* :
1. attendre la fin du processus d'intégration/développement continu (lancé
automatiquement sur notre instance GitLab lorsqu'ils les "poussent" sur le
dépôt du projet) ;
2. aller (à nouveau) consulter en ligne sur le site
https://faq.gutenberg-asso.fr/ les pages .`html` correspondantes
(ré)générées.
Ces contributeurs peuvent (devraient ?) préférer compiler la FAQ en local sur
leur machine car cela présente au moins trois avantages :
- ils peuvent ainsi ne publier qu'après contrôle en local des effets de leurs
modifications ;
- pour un unique fichier modifié, la compilation ne dure que quelques secondes
ce qui permet un contrôle rapide ;
- le "log" de la compilation permet d'avoir connaissance de certains problèmes
(éventuellement créés par les modifications venant d'être apportées).
Pour pouvoir compiler en local la FAQ, il y a au moins deux méthodes :
1. *pas* via une image Docker ;
2. via une image Docker.
:::{attention}
Nous avons testé ces méthodes avec le système d'exploitation GNU/Linux et les
détaillons donc dans ce cadre. Sous macOS, ce devrait être similaire.
:::
:::{todo}
Transposer pour Windows les détails (donnés pour GNU/Linux) des méthodes
permettant de compiler la FAQ en local.
:::
## Méthode n'utilisant pas d'image Docker
Cette méthode nécessite l'installation, essentiellement dans un environnement
virtuel, de logiciels en local sur la machine du contributeur. Elle suppose en
outre :
- l'usage de commandes lancées dans un terminal ;
- l'usage du logiciel `git` (non documenté ici) ;
- le clonage de dépôts `git` hébergés sur [l'instance GitLab de
GUTenberg](https://gitlab.gutenberg-asso.fr/). Ceci peut être fait de deux
façons :
- soit, de préférence, avec `ssh` (ce qui suppose un compte ouvert puis une
clé publique enregistrée sur notre instance GitLab) ;
- soit, ce qui est plus simple mais moins pratique, avec `https`.
% Cette méthode repose sur les étapes suivantes.
% (dont les lignes de commandes sont résumées en fin de procédure).
### Étapes à suivre la première fois
1. Si ce n'est déjà fait, installez `git`.
2. Si ce n'est déjà fait, installez `python` et `python3-venv`.
3. Si ce n'est déjà fait, clonez le dépôt de la FAQ :
- soit avec `ssh` :
```bash
git clone ssh://git@gitlab.gutenberg-asso.fr:31022/gutenberg/faq-gut.git
```
- soit avec `https` :
```bash
git clone https://gitlab.gutenberg-asso.fr/gutenberg/faq-gut.git
```
4. Rendez-vous dans le dossier du dépôt cloné et créez-y un dossier `build` :
```bash
cd faq-gut
mkdir build
```
5. Créez puis activez un environnement virtuel `python`, par exemple nommé
`.venv` et placé dans un sous-dossier (caché) du dossier `build` :
```bash
python3 -m venv build/.venv
source build/.venv/bin/activate
```
(L'activation de l'environnement virtuel modifie le *prompt* de votre ligne de
commande en le faisant précéder du nom choisi pour cet environnement virtuel.)
6. Installez certains modules `python` nécessaires à la compilation de la FAQ
(dont bien sûr `Sphinx-doc`) :
```bash
python3 -m pip install --no-cache-dir -U pip
python3 -m pip install --no-cache-dir \
Sphinx \
Pillow \
sphinx_comments \
sphinx_design \
sphinxext.opengraph \
myst_parser \
linkify-it-py \
sphinx_tippy \
sphinx_sitemap \
pydata_sphinx_theme \
sphinx_copybutton \
sphinx_togglebutton \
sphinx_examples \
sphinx_last_updated_by_git
```
7. Clonez le dépôt `pygments-acetexlexer` (module `python` enrichissant le
surligneur syntaxique `Pygments`) :
- soit avec `ssh` :
```bash
git clone ssh://git@gitlab.gutenberg-asso.fr:31022/dbitouze/pygments-acetexlexer.git
```
- soit avec `https` :
```bash
git clone https://gitlab.gutenberg-asso.fr/dbitouze/pygments-acetexlexer.git
```
8. Rendez-vous dans le dossier du dépôt cloné, installez le module
correspondant puis supprimez le dépôt devenu inutile :
```bash
cd pygments-acetexlexer
python3 -m pip install --no-cache-dir .
cd ..
rm -rf pygments-acetexlexer
```
9. Dans le dossier de la FAQ (où vous devriez vous trouver), lancez la
compilation de cette dernière (pour cette première fois, complète et donc un
peu longue) :
```bash
sphinx-build -j auto source build/html
```
Vous verrez éventuellement apparaître un certain nombre de *warnings*
signalant, comme lors d'une compilation LaTeX, de potentiels problèmes.
Lorsque cette compilation est achevée, vous pouvez consulter dans un
navigateur Web la FAQ construite localement sur votre machine. Il suffit pour
ce faire de lancer la commande (ici pour le navigateur Firefox) :
```bash
firefox build/html/index.html &
```
puis de naviguer dans la FAQ comme vous le feriez en ligne.
10. Apportez des modifications à un ou plusieurs fichiers sources `.md` du
dossier `source` (au début par exemple au fichier
`source/8_contribuer/bac-a-sable.md`, si vous craignez de casser quelque
chose) puis relancez la compilation (cette fois, seulement du ou des fichiers
modifiés et donc rapide) :
```bash
sphinx-build -j auto source build/html
```
Vous pouvez alors consulter vos modifications. Par
exemple, celles qui auraient été apportées au fichier
`source/8_contribuer/bac-a-sable.md` pourraient être consultées en lançant :
```bash
firefox build/html/8_contribuer/bac-a-sable.html &
```
(à bien entendu ne pas lancer après chaque compilation : le rafraîchissement
dans le navigateur de cette page `.html` est suffisant).
11. Lorsque vos modifications vous conviennent, vous pouvez les "pousser" sur le
dépôt de la FAQ et elles apparaîtront en ligne au plus tard quelques minutes
après.
### Étapes à suivre les fois suivantes
Bien entendu, la plupart des étapes précédentes n'ont besoin d'être suivies que
la première fois. Toutefois, les fois suivantes, si entre temps vous avez par
exemple relancé la, ou changé de, session de terminal ou bien si vous avez
éteint votre machine, il faudra veiller à bien réactiver l'environnement virtuel
`python` avant de pouvoir à nouveau compiler la FAQ en local. Pour ce faire, une
fois rendu dans le dossier de la FAQ, lancez la commande :
```bash
source build/.venv/bin/activate
```
## Méthode utilisant une image Docker
:::{todo} Compléter la méthode utilisant une image Docker pour compiler la FAQ
en local.
:::