Aller au contenu

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

logo console terminal

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 :

Il est également recommandé :

Tip

Pour aborder de façon sympathique le fonctionnement du site web, pourquoi ne pas commencer par suivre le tutoriel publié fin 2020 pour déployer Geotribu localement ?

Toi aussi, déploie le site Geotribu chez toi


Git#

logo 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 !

Pour avoir une version récente de Git, il faut ajouter les dépôts communautaires :

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

Il "suffit" d'utiliser l'installateur à télécharger depuis le site officiel. Quelques ressources tout de même :

Récupérer le site localement#

Cloner le dépôt :

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.

Et le SSH alors ?!

Pourquoi je ne mentionne pas la possibilité de cloner par SSH ? Parce-que si vous vous posez cette question, c'est que vous n'avez pas du tout besoin de lire cette partie-là car, félicitations : vous avez un niveau en Git supérieur à un quickstart ! 🥳

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#

logo 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

Le mieux est encore de suivre l'article dédié :

Python : installation et configuration sur Windows

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

Si ça n'est pas encore fait, il faut autoriser l'utilisation des environnements virtuels.
Puis :

 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

A exécuter régulièrement

Les dépendances du projet sont mises à jour mensuellement. Il est donc recommandé de mettre son environnement virtuel local à jour avant de contribuer, avec la commande :

python -m pip install -U -r requirements-free.txt


Pre-commit#

logo 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#

icône générateur de site web statique

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.

Fichier Fonctionnalités payantes Complet Commentaire
mkdocs.yml X X Configuration complète utilisée pour le site en production. Utilisé par défaut.
mkdocs-free.yml X Configuration sans les fonctionnalités payantes (tags, etc.)
mkdocs-minimal.yml Configuration minimaliste qui n'active qu'un minimum de plugins et d'extensions pour obtenir de meilleures performances lors de l'édition en local.

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#

logo 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


  1. étape où un contributeur propose d'intégrer ses modifications dans le socle principal du projet. Voir la documentation de GitHub

Commentaires