Skip to content

Contributing Documentation

For this project, we use ProperDocs, the maintained fork of MkDocs, for the documentation. Here is some information to help you contribute to the documentation.

Prerequisites

We recommend installing a Python virtual environment to install ProperDocs.

Python 3.6 or higher is required to install ProperDocs.

Installing the Python environment

To install Python, open a terminal (PowerShell) to install the bucket:

scoop bucket add main

scoop install main/python

For more information, visit https://scoop.sh/#/apps?q=python

To install Python, open a terminal (PowerShell) to install the package:

choco install python

For more information, visit https://community.chocolatey.org/packages/python

To install Python, open a terminal

brew install python@3.12

For more information, visit https://formulae.brew.sh/formula/python

Generating social cards (the material/social plugin) uses cairosvg, which requires the native cairo library:

brew install cairo

Installing the Python virtual environment

Create a Python virtual environment with the following command:

python3 -m venv venv

macOS: check your Python

If python3 is the Python shipped by Apple (/usr/bin/python3 or /Library/Developer/CommandLineTools/...), the venv will not find the libraries installed with Homebrew and properdocs serve will fail with the error no library called "cairo-2" was found.

Check with command -v python3 that you are using Homebrew's Python (/opt/homebrew/bin/python3) before creating the venv.

Virtual ENVironment

Why use a Python virtual environment? https://docs.python.org/3/library/venv.html

Activating the virtual environment

To activate the Python virtual environment, open a terminal and type the following command:

Open a terminal (PowerShell):

_venv_\Scripts\Activate.ps1

Open a terminal (CMD):

venv\Scripts\activate.bat

Open a terminal

source venv/bin/activate

Installing ProperDocs

To install ProperDocs, type the following command. This command installs ProperDocs and the required dependencies.

python -m pip install -r requirements.txt

Going further

We use the "Material" theme for the documentation.

For more information, visit https://squidfunk.github.io/mkdocs-material/

ProperDocs is the maintained fork of MkDocs, as the original project has no longer been maintained since August 2024.

For more information, visit https://properdocs.org/

Running ProperDocs

properdocs serve

ProperDocs starts a local server so you can preview the documentation.

Open a browser and go to https://127.0.0.1:8000/edu-framework/

A bilingual documentation

The documentation is available in French (default language) and in English.

  • Each page page.md (in French) can have an English counterpart page.en.md in the same folder.
  • The English navigation is defined in the docs/_summary.en.md file (the French navigation is in docs/_summary.md).
  • A page without a .en.md file is displayed in French in the English version of the site.
  • In links between pages, always point to the French file name (page.md): the English version is resolved automatically.

Keep both versions in sync

When you edit a page, please update both versions (page.md and page.en.md) whenever possible. If you cannot translate your changes, mention it in your pull request.

Once installed

Once installed, you can contribute to the documentation by editing the Markdown files in the project's "docs" folder. Remember to work on the "main" branch for your changes and to open a pull request to have them validated.

If you closed the terminal, remember to activate the Python virtual environment before running ProperDocs.