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 :

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

pas via une image Docker ;
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.

À faire

Transposer pour Windows les détails (donnés pour GNU/Linux) des méthodes permettant de compiler la FAQ en local.

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

1.1. Étapes à suivre la première fois#

Si ce n’est déjà fait, installez git.
Si ce n’est déjà fait, installez python et python3-venv.

Si ce n’est déjà fait, clonez le dépôt de la FAQ :

soit avec ssh :

git clone ssh://git@gitlab.gutenberg-asso.fr:31022/gutenberg/faq-gut.git

soit avec https :

git clone https://gitlab.gutenberg-asso.fr/gutenberg/faq-gut.git

Rendez-vous dans le dossier du dépôt cloné et créez-y un dossier build :
```
cd faq-gut
mkdir build
```
Créez puis activez un environnement virtuel python, par exemple nommé .venv et placé dans un sous-dossier (caché) du dossier de la FAQ :
```
python3 -m venv .venv
source .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.)

Installez certains modules python nécessaires à la compilation de la FAQ (dont bien sûr Sphinx-doc) :

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

Clonez le dépôt pygments-acetexlexer (module python enrichissant le surligneur syntaxique Pygments) :

soit avec ssh :

git clone ssh://git@gitlab.gutenberg-asso.fr:31022/dbitouze/pygments-acetexlexer.git

soit avec https :

git clone https://gitlab.gutenberg-asso.fr/dbitouze/pygments-acetexlexer.git

Rendez-vous dans le dossier du dépôt cloné, installez le module correspondant puis supprimez le dépôt devenu inutile :
```
cd pygments-acetexlexer
python3 -m pip install --no-cache-dir .
cd ..
rm -rf pygments-acetexlexer
```
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) :
```
.venv/bin/sphinx-build -j auto source build/html
```
En principe, vous devriez obtenir le même effet avec la commande suivante :
```
make 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) :
```
firefox build/html/index.html &
```
puis de naviguer dans la FAQ comme vous le feriez en ligne.
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) :
```
.venv/bin/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 :
```
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).
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.

1.2. É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 :

source .venv/bin/activate

2. Méthode utilisant une image Docker#

À faire

Compléter la méthode utilisant une image Docker pour compiler la FAQ en local.