---
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 de la FAQ :
   ```bash
   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.)
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
   .venv/bin/sphinx-build -j auto source build/html
   ```

   En principe, vous devriez obtenir le même effet avec la commande suivante :
   ```bash
   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) :
   ```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
    .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 :
    ```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 .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.
:::