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
etpython3-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 dossierbuild
: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.)
Installez certains modules
python
nécessaires à la compilation de la FAQ (dont bien sûrSphinx-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
(modulepython
enrichissant le surligneur syntaxiquePygments
) :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) :
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) :
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 dossiersource
(au début par exemple au fichiersource/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) :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 build/.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.