Aller au contenu

Installation pour l'édition locale#

Tip

Remplir d'abord les prérequis. Les chemins de fichiers et répertoires sont à adapter à votre environnement.

Git#

La mise en ligne du contenu se fait via Git. Si vous n'êtes pas à l'aise avec la ligne de commande, il est possible d'utiliser GitHub Desktop.

Cloner le dépôt, soit avec la commande ci-dessous, soit via le bouton vert sur le dépôt avec GitHub Desktop :

1
2
cd ~/git-repos/geotribu/
git clone --depth=1 https://github.com/geotribu/website.git

Python#

Pour éditer localement et visualiser le résultat final avant de publier sur le dépôt, il faut installer Python 3.7 ou supérieure et les dépendances du projet. Exemple avec Ubuntu 18. 04 et Windows 10 (quelques adaptations peuvent être nécessaires):

 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 à son environnement
cd ~/git-repos/geotribu/website/

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

# si aucune version supérieure ou égale à 3.7 n'est installée, installons la dernière
sudo apt install python3.8

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# se rendre à la racine du dépôt local - adapter à son environnement
cd ~/git-repos/geotribu/website/

# si besoin, autoriser l'utilisation des environnements virtuels
# commande à exécuter dans Powershell en mode administrateur (puis quitter le mode admin avant de continuer)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

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

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

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

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

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

Tip

Le projet est configuré pour mettre semi-automatiquement à jour certaines dépendances. Il est donc recommandé de mettre son environnement virtuel local à jour avant de contribuer : pip install -U -r requirements.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 par Github Action.

Installer pre-commit :

1
2
# installer
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 les exécuter manuellement :

1
pre-commit run -a

Servir en local#

Puis de lancer la commande qui lance le site en local avec rechargement automatique :

1
2
3
4
5
6
7
8
# servir le site avec mkdocs
mkdocs serve

# il existe aussi un mode où le rechargement automatique est plus rapide mais ne concerne que la page modifiée
mkdocs serve -f mkdocs-minimal.yml --dirtyreload

# si besoin, il est évidemment possible de spécifier le port
mkdocs serve -f mkdocs-minimal.yml --dirtyreload -a localhost:8085

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

Docker#

Il est possible de se passer de Python en utilisant Docker.

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

Le site est accessible sur : http://localhost:8000

Mettre à jour son dépôt local#

Après qu'une branche ait été fusionnée (merged), elle est automatiquement supprimée par GitHub afin d'éviter de garder un trop grand nombre de branches. Il faut alors mettre à jour le dépôt local sur votre machine :

1
2
3
4
5
# 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
git branch --merged | grep -i -v -E "master|gh-pages"| xargs git branch -d

1
2
3
4
5
# 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

# ouvre une fenêtre de sélection des branches à supprimer
git branch --format "%(refname:short)" --merged  | Out-GridView -PassThru | % { git branch -d $_ }
Dernière mise à jour: 24 septembre 2021
Créé: 24 septembre 2021
Contributions à cette page : Julien Moura

Ce contenu est sous licence Creative Commons BY-NC-SA 4.0 International

Commentaires

Une version minimale de la syntaxe markdown est acceptée pour la mise en forme des commentaires.
Propulsé par Isso.
Retour en haut de la page