Installation et configuration de l'environnement de travail pour l'édition locale#

Cette page a pour but de vous guider dans les principales étapes afin de pouvoir gérer le site et ses contenus depuis une machine locale. Il est probable que chacun/e doive ajuster selon son propre environnement de travail (chemins de fichiers, répertoires...).

Après avoir rempli les prérequis généraux, pour travailler sur le site en local, il faut donc :

• Git
• Python

Il est également recommandé :

• d'avoir une connexion autorisée vers le CDN de Geotribu
• d'installer Node.js (LTS) pour pouvoir utiliser markdownlint (voir Rédiger en Markdown : enjeux de qualité et règles).

Git#

La gestion et la mise en ligne du contenu se font via Git, une suite d'outils en ligne de commande (CLI). Si vous n'êtes pas à l'aise avec la ligne de commande, il est possible d'utiliser GitHub Desktop en suivant la documentation officielle.

Installation#

Il y a beaucoup de ressources sur la Toile pour installer et configurer Git.
Nous mettons ici une documentation minimaliste destinée à donner la trame globale de l'installation de Git, mais il y a fort à parier que cette documentation soit trop générique. A chacun/e de trouver tuto à son pied si besoin !

1
2
3

sudo add-apt-repository ppa:git-core/ppa
sudo apt update
sudo apt install git

Récupérer le site localement#

Cloner le dépôt :

• soit via le bouton vert sur le dépôt avec GitHub Desktop. Dans ce cas-là, ouvrez un terminal Powershell dans le dossier décompressé et passez à l'étape suivante.
• soit avec les commandes ci-dessous :

1
2

cd ~/git-repos/geotribu/
git clone https://github.com/geotribu/website.git

Ce qui donne :

1
2
3
4
5
6
7

Clonage dans 'website'...
remote: Enumerating objects: 46677, done.
remote: Counting objects: 100% (1754/1754), done.
remote: Compressing objects: 100% (170/170), done.
remote: Total 46677 (delta 840), reused 1705 (delta 827), pack-reused 44923
Réception d'objets: 100% (46677/46677), 59.82 Mio | 10.49 Mio/s, fait.
Résolution des deltas: 100% (36595/36595), fait.

Configurer Git#

Il s'agit d'indiquer le nom et l'adresse email qui seront utilisés pour les commits. Par exemple, si vous vous appelez Mona Lisa :

1
2
3
4

# on se déplace dans le dossier qui contient le sous dossier caché '.git'
cd website
git config user.name "Mona Lisa"
git config user.email "mona.lisa@devinci.com"

Mettre à jour son dépôt local#

Vérifier que votre dépôt local (sur votre ordinateur) soit à jour par rapport au dépôt central (sur GitHub) :

1
2

git fetch --prune
git status

Ce qui donne :

1
2
3
4

Sur la branche master
Votre branche est à jour avec 'origin/master'.

rien à valider, la copie de travail est propre

Si la commande git status ne vous renvoie pas le même genre de message qu'au-dessus, cela signifie que vous n'êtes pas à jour. Il faut alors faire :

1

git pull origin --prune

Après qu'une branche ait été fusionnée (merged), elle est automatiquement supprimée sur le dépôt central (hébergé sur GitHub) afin de garder un dépôt propre et lisible. Il faut alors mettre à jour le dépôt local sur votre machine :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

git pull origin

# mettre le dépôt local en conformité avec le dépôt central (notamment en supprimant les branches locales déjà supprimées sur GitHub)
git remote prune origin

# supprimer les branches qui ont été fusionnées - sauf master et gh-pages
git branch --merged | grep -i -v -E "master|gh-pages"| xargs git branch -d

# supprimer les branches qui n'existent plus sur GitHub
git fetch --prune && git branch -v | grep -i -E "\[disparue|gone\]" | grep -v -E "\*|master|main|gh-pages" | awk '{print $1}' | xargs git branch -D

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

git pull origin

# mettre le dépôt local en conformité avec le dépôt central (notamment en supprimant les branches locales déjà supprimées sur GitHub)
git remote prune origin

# supprimer les branches qui ont été fusionnées - sauf master et gh-pages
git branch --merged | Select-String -Pattern '^(?!.*(master|gh-pages)).*$' | ForEach-Object { git branch -d $_.ToString().Trim() }

# ou en ouvrant une fenêtre de sélection des branches à supprimer
git branch --format "%(refname:short)" --merged  | Out-GridView -PassThru | % { git branch -d $_ }

Python#

Pour éditer localement et visualiser le résultat final avant de publier sur le dépôt, il faut installer Python 3.10 ou supérieure et les dépendances du projet.

Installation de Python#

1
2
3
4
5
6
7
8

# lister les versions de Python installées
ls -1 /usr/bin/python* | grep '[2-3].[0-9]$'

# si aucune version de Python >= 3.10 n'est installée, installons la 3.10 par exemple
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.10

Création de l'environnement de travail#

Pour travailler tranquillement sans risquer de casser quoi que ce soit dans l'installation de Python au niveau du système, on préfère utiliser un environnement virtuel.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# se rendre à la racine du dépôt local - adapter au dossier dans lequel vous avez cloné le dépôt
cd ~/git-repos/geotribu/website/

# créer un environnement virtuel
python3 -m venv .venv
source .venv/bin/activate

# mettre à jour pip et les outils de packaging
python -m pip install -U pip
python -m pip install -U setuptools wheel

# installer les dépendances
python -m pip install -U -r requirements-free.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# se rendre à la racine du dépôt local - adapter au dossier dans lequel vous avez cloné le dépôt
cd ~/git-repos/geotribu/website/

# lister les versions de Python installées
py --list

# créer un environnement virtuel - Attention : ne fonctionne pas avec Python installé depuis le Windows Store
py -3.10 -m venv .venv  

# activer l'environnement virtuel
.\.venv\Scripts\activate

# mettre à jour pip
python -m pip install -U pip
python -m pip install -U setuptools wheel

# installer les dépendances
python -m pip install -U -r requirements-free.txt

Pre-commit#

Le projet vient avec une configuration pour pre-commit, qui permet d'appliquer des scripts (des git hooks) de vérification et de nettoyage des fichiers avant qu'ils ne soit enregistrés dans le dépôt (d'où le nom).

L'installation est optionnelle mais recommandée car l'outil garantit :

• un socle minimal de qualité des contenus et codes sources
• une cohérence d'ensemble entre les contributions
• qu'une fois poussée sur le dépôt central, la contribution passe les checks exécutés dans la CI.

En savoir plus sur les crochets Git

Installer pre-commit :

1
2

# depuis l'intérieur de l'environnement virtuel
pre-commit install

Une fois installés, les scripts s'exécuteront à chaque commit. Ne pas se laisser impressionner par les messages verbeux :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

> git commit

[WARNING] Unstaged files detected.
[INFO] Stashing unstaged files to C:/Users/mPokora/.cache/pre-commit/patch1588143245.
Trim Trailing Whitespace.............................(no files to check)Skipped
Detect Private Key...................................(no files to check)Skipped
Fix End of Files.....................................(no files to check)Skipped
Check Yaml...........................................(no files to check)Skipped
Check for added large files..........................(no files to check)Skipped
[INFO] Restored changes from C:/Users/mPokora/.cache/pre-commit/patch1588143245.

Il est également possible de tous les exécuter manuellement :

1

pre-commit run -a

Mkdocs#

C'est l'outil qui sert à générer le site web à partir des contenus rédigés en markdown et configuré dans le fichier mkdocs.yml et dérivés. Voici quelques bases pour l'utiliser... qui ne vous épargnent pas le droit de regarder l'aide mkdocs --help .

Différentes configurations#

Depuis la rentrée 2021, Geotribu sponsorise le thème Material for Mkdocs afin de pérenniser le projet et tirer parti des fonctionnalités réservées aux financeurs. La clé de licence (en fait, un token GitHub lié au compte de Julien) devant rester secrète, nous gérons donc plusieurs fichiers de configuration afin de pouvoir s'adapter aux différents cas.

Générer le site web#

Version complète :

1

mkdocs build

Version complète gratuite :

1

mkdocs build -f mkdocs-free.yml

Version minimale :

1

mkdocs build --config-file mkdocs-minimal.yml

Le site généré est dans le répertoire : /home/runner/work/site-contribuer/site-contribuer/build/mkdocs/site.

Avoir un rendu local mis à jour selon les modifications#

Pour voir les changements en local sans les pousser sur le dépôt central, il est possible de servir le site et qu'il se recharge automatiquement quand on modifie les fichiers :

Version complète :

1
2
3
4

# regénération complète
mkdocs serve
# regénération rapide
mkdocs serve --dirtyreload

Version complète gratuite :

1
2
3
4

# regénération complète
mkdocs serve -f mkdocs-free.yml --dirtyreload
# regénération rapide
mkdocs serve --config-file mkdocs-free.yml --dirtyreload

Version minimale :

1
2
3
4

# regénération complète
mkdocs serve --config-file mkdocs-minimal.yml
# regénération rapide
mkdocs serve --config-file mkdocs-minimal.yml --dirtyreload

Par défaut, le site est accessible sur http://localhost:8000 mais il est possible de spécifier le port à utiliser : mkdocs serve -a localhost:8085.

Docker#

Il est également possible d'utiliser Docker. L'avantage est que c'est alors la seule dépendance à installer (plus besoin de Python, NodeJS ou même de Git si vous téléchargez le dépôt). L'inconvénient est que c'est assez lourd pour un site qui se veut léger !

1

docker-compose -f "docker-compose-mkdocs.dev.yml" up --build

Le site est alors accessible sur : http://0.0.0.0:8000

Commentaires