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 :
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).
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 ?
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 |
|
Il "suffit" d'utiliser l'installateur à télécharger depuis le site officiel. Quelques ressources tout de même :
- la documentation Microsoft
- le tutoriel d'Astuces Informatiques
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 |
|
Ce qui donne :
1 2 3 4 5 6 7 |
|
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 |
|
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 |
|
Ce qui donne :
1 2 3 4 |
|
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 |
|
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 |
|
1 2 3 4 5 6 7 8 9 10 |
|
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 |
|
Le mieux est encore de suivre l'article dédié :
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 |
|
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 |
|
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#
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 |
|
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 |
|
Il est également possible de tous les exécuter manuellement :
1 |
|
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.
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 |
|
Version complète gratuite :
1 |
|
Version minimale :
1 |
|
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 |
|
Version complète gratuite :
1 2 3 4 |
|
Version minimale :
1 2 3 4 |
|
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 |
|
Le site est alors accessible sur : http://0.0.0.0:8000
-
étape où un contributeur propose d'intégrer ses modifications dans le socle principal du projet. Voir la documentation de GitHub. ↩