Aller au contenu

Contributing Documentation

Pour ce projet, nous utilisons ProperDocs, le fork maintenu de MkDocs, pour la documentation. Voici quelques informations pour vous aider à contribuer à la documentation.

Prérequis

Nous vous recommandons d'installer l'environnement virtuel Python pour installer ProperDocs.

Python 3.6 ou supérieur est requis pour l'installation de ProperDocs.

Installation de l'environnement Python

Pour installation Python, ouvrez un terminal (PowerShell) pour installer le bucket :

scoop bucket add main

scoop install main/python

Pour plus informations, visitez le site https://scoop.sh/#/apps?q=python

Pour installation Python, ouvrez un terminal (PowerShell) pour installer le bucket :

choco install python

Pour plus informations, visitez le site https://community.chocolatey.org/packages/python

Pour installation Python, ouvrez un terminal

brew install python@3.12

Pour plus informations, visitez le site https://formulae.brew.sh/formula/python

La génération des cartes sociales (plugin material/social) utilise cairosvg, qui nécessite la bibliothèque native cairo :

brew install cairo

Installation de l'environnement virtuel Python

Créer un environnement virtuel Python avec la commande suivante :

python3 -m venv venv

macOS : vérifiez votre Python

Si python3 correspond au Python fourni par Apple (/usr/bin/python3 ou /Library/Developer/CommandLineTools/...), le venv ne trouvera pas les bibliothèques installées via Homebrew et properdocs serve échouera avec l'erreur no library called "cairo-2" was found.

Vérifiez avec command -v python3 que vous utilisez bien le Python de Homebrew (/opt/homebrew/bin/python3) avant de créer le venv.

ENVironnement Virtuel

Pourquoi utiliser un environnement virtuel Python ? https://docs.python.org/3/library/venv.html

Activation de l'environnement virtuel

Pour activer l'environnement virtuel Python, ouvrez un terminal et tapez la commande suivante :

Ouvrez un terminal (PowerShell) :

_venv_\Scripts\Activate.ps1

Ouvrez un terminal (CMD) :

venv\Scripts\activate.bat

Ouvrez un terminal

source venv/bin/activate

Installation de ProperDocs

Pour installer ProperDocs, tapez la commande suivante : Cette commande va installer ProperDocs et les dépendances nécessaires.

python -m pip install -r requirements.txt

Pour aller plus loin

Nous utilisons le thème "Material" pour la documentation.

Pour plus d'informations, visitez le site https://squidfunk.github.io/mkdocs-material/

ProperDocs est le fork maintenu de MkDocs, le projet original n'étant plus maintenu depuis août 2024.

Pour plus d'informations, visitez le site https://properdocs.org/

Lancement de ProperDocs

properdocs serve

ProperDocs va lancer un serveur local pour visualiser la documentation.

Ouvrez un navigateur et tapez l'adresse https://127.0.0.1:8000/edu-framework/

Une documentation bilingue

La documentation est disponible en français (langue par défaut) et en anglais.

  • Chaque page page.md (en français) peut avoir son équivalent anglais page.en.md dans le même dossier.
  • La navigation anglaise est définie dans le fichier docs/_summary.en.md (la navigation française se trouve dans docs/_summary.md).
  • Une page sans fichier .en.md est affichée en français dans la version anglaise du site.
  • Dans les liens entre pages, pointez toujours vers le nom du fichier français (page.md) : la version anglaise est résolue automatiquement.

Garder les deux versions à jour

Lorsque vous modifiez une page, mettez à jour les deux versions (page.md et page.en.md) dans la mesure du possible. Si vous ne pouvez pas traduire vos modifications, signalez-le dans votre pull request.

Une fois installé

Une fois installé, vous pouvez contribuer à la documentation en modifiant les fichiers Markdown dans le dossier "docs" du projet. N'oubliez pas de travailler sur la branche "main" pour vos modifications et de faire une pull request pour les valider.

Si vous avez fermé le terminal, n'oubliez pas d'activer l'environnement virtuel Python avant de lancer ProperDocs.