Installation
The following tools are needed to compile the markdown documents into HTML pages.
- mkdocs: the main tool to generate the static website
- mkdocs-material: the used material-style theme
- mike: the versioning tool, based on mkdocs
Environment Installation
In order to install mkdocs, you need to have Python >= 3.8 and pip installed.
The required dependencies for building the documentation can be found in the root folder requirement.txt file. For installing them we suggest using a Python Virtual Environment.
Create a virtual environment as follows:
this will create a folder in you current path named .venv. Activate the virtual environment with:
you're now using the virtual environment, update pip and install the required dependencies.
You're now ready do build the documentation sources locally.
Tip: Version Collisions
The installations into the Python virtual environment can sometimes conflict with other versions of the same software installed on the system. The active version should be the version installed into the Python virtual environment you are working in. This can affect mkdocs (and other programs if they added to the requirements.txt).
Check the path of the program you want to run (which mkdocs on MacOS and Linux). If this doesn't point to the active Python virtual environment, reload the virtual environment: