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. Les mêmes instructions sont valables à quelques modifications éventuelles près pour macOS.

À 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 de logiciels en local sur la machine du contributeur, et ceci principalement dans un environnement Python virtuel via pip install ;

  • le clonage du dépôt git de la FAQ qui est hébergé sur l’instance GitLab de GUTenberg ;

  • l’emploi de commandes (make, git) lancées dans un terminal, avec l’environnment virtuel Python activé, afin de tester en local puis de contribuer vos changements.

1.1.  É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. Clonez le dépôt de la FAQ. Ceci peut être fait de deux façons (voir Édition en clonant le dépôt pour une description plus détaillée) :

    • soit avec ssh, ce qui suppose un compte ouvert et une clé publique enregistrée sur notre instance GitLab :

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

    • soit avec https, ce qui n’est pratique sur le long terme que si le mécanisme du credential.helper de git est mis en oeuvre afin de ne pas avoir à redonner son nom d’utilisateur GitLab et le mot de passe associé à chaque « push » :

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

  4. Créez un environnement virtuel python, par exemple nommé .venv et placé dans un sous-dossier (caché) du dossier de la FAQ :

    python3 -m venv .venv

  5. Activez l’environnement virtuel .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) :

    python3 -m pip install -U pip
python3 -m pip install    \
      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. Installez pygments-acetexlexer (module python enrichissant le surligneur syntaxique Pygments) :

    python3 -m pip install git+https://gitlab.gutenberg-asso.fr/dbitouze/pygments-acetexlexer.git@main

  8. Dans le dossier de la FAQ (où vous devriez vous trouver avec l’environnement virtuel .venv actif), lancez la compilation de cette dernière :

    make html

    Pour cette première fois, la compilation sera complète et donc un peu longue.

    Note

    En principe, vous devriez obtenir le même effet avec la commande suivante :

    sphinx-build -j auto source build/html -d build/doctrees

    Mais il n’y a pas de raison de l’utiliser plutôt que make html.

    Vous verrez éventuellement apparaître un certain nombre de warnings signalant, comme lors d’une compilation de potentiels problèmes, dont certains peuvent être ignorés.

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

    Note

    Sur macOS, utilisez open build/html/index.html.

1.2.  Faire des modifications et les intégrer au dépôt#

Il est très important de veiller à bien réactiver l’environnement virtuel .venv avant toute tentative de compilation de la FAQ en local, si vous avez depuis la dernière fois fermé votre session ou votre terminal pour les commandes en ligne.

Une fois rendu à nouveau dans le dossier de la FAQ, lancez, si l’environnement virtuel n’est pas déjà actif, la commande :

source .venv/bin/activate

Puis, exécutez git pull pour intégrer les modifications distantes et make html pour mettre à jour les fichiers html (ces fichiers bien sûr ne sont pas intégrés au contrôle de version git, seuls ceux du répertoire source, et quelques autres d’une nature technique, le sont).

Vous pouvez alors commencer à apporter des modifications à un ou plusieurs fichiers sources .md du dossier source. Pour vous entraîner « à blanc », vous pouvez modifier le fichier source/8_contribuer/bac-a-sable.md, si vous craignez de casser quelque chose.

Testez vos modifications par make html. Seuls les fichiers html impactés par les modifications seront reconstruits et le processus devrait a priori être rapide.

Lorsque vos modifications vous conviennent, vous pouvez en faire un « commit » avec les commandes usuelles du type git commit -a. Si au contraire vous voulez vous en débarrasser faites git stash puis éventuellement git stash drop. Si vous avez déjà fait des commits en local et que leur organisation ne convient pas vous pouvez exécuter git reset origin/main pour conserver les fichiers modifiés mais annuler les commits associés. Ou git reset --hard origin/main pour tout oublier et annuler totalement vos modifications.

Une fois vos commits satisfaisants il suffira de git push pour les « pousser » sur le dépôt de la FAQ. Vos modifications apparaîtront en ligne au plus tard quelques minutes après.

Indication

Plus précisément, deux possibilités avec le git push :

  • la procédure aboutit,

  • ou le dépôt de la FAQ a été modifié entre-temps, et le « push » ne peut aboutir.

Dans ce dernier cas :

  • git fetch pour récupérer les modifications distantes dans origin/main,

  • puis git rebase origin/main pour que votre branche main locale soit un descendant de la branche main du dépôt.

  • git push pourra alors (enfin !) mettre à jour le dépôt avec vos propres modifications.

Dans certains cas l’étape git rebase après le git fetch aura donné lieu à des conflits car des modifications distantes seront rentrées en collision avec celles apportées par vos soins. La résolution de ces conflits est la routine pour les utilisateurs expérimentés de git, mais il faut donc une certaine expérience avec git pour fonctionner suivant ces mécanismes.

Les commandes comme git merge créent un historique plus embrouillé et moins linéaire et il est donc toujours préférable de procéder par git rebase origin/main depuis votre branche main ayant des commits supplémentaires, puis git push.

2.  Méthode utilisant une image Docker#

À faire

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