How to write MkDocs Documentation

The method below allows you to write and preview the doc easily thanks to VSCode and either:

Python (preferred) Dev Container

Important

We do not provide enhanced documentation for both usages, but further inormation can be found from:

• Python: a pyproject.toml file is available at the root of the documentation to install required packages inside a uv Python environment.
• Dev Container: one can consult the content of the .devcontainer folder to install the required programs and tools to build the documentation on its own.

Quick start (Python)

Requirements

• Visual Studio Code
• Just
• uv

Usage

Clone the repository and open the folder in VSCode:

git clone https://gitlab.hevs.ch/SPL/spl-docs.git
cd spl-docs
code .

To build the site locally and preview changes, run in a command prompt:

just serve

   and then open a web browser, the site preview being available under http://127.0.0.1:8000/ (default).

Changes are automatically updated in the browser when the source files are saved.

Then check the chapter Commiting your changes to know how to update the online documentation.

Quick start (Dev Container)

Requirements

• Visual Studio Code
  • Dev Containers extension
• Docker engine
• Just
• uv

Usage

Run the docker engine.

Clone the repository and open the folder in VSCode:

git clone https://gitlab.hevs.ch/SPL/spl-docs.git
cd spl-docs
code .

The .devcontainer folder within the root of the documentation will be detected by VSCode. It will ask you to open the folder in a container, confirm the action.

Info

If the dialog doesn't show up, open the command palette (Ctrl+Shift+P or F1) and search for Dev Containers: Open Folder in Container....

Once the container is built, you are ready to read and write some doc. A live preview is available under http://127.0.0.1:8000/ (default).

Changes are automatically updated in the browser when the source files are saved.

Then check the chapter Commiting your changes to know how to update the online documentation.

Commiting your changes

Available commands

This documentation comes with a justfile (Makefile replacement). Use just to see the availabe recipes:

just --list
Available recipes:
    build                                  # Build HTML static site
    changelog                              # create the changelog of the project
    changelog-release version=git-tag      # create a release version of the project
    clean                                  # clean build folder and venv
    clean-build                            # Delete build folder
    clean-venv                             # Delete venv
    deploy                                 # Deploy on gh-pages
    info                                   # Information about the environment
    serve                                  # Build HTML static site and serve it locally
    uv-create requirements=env_export_file # Create new uv environment from old requirements.txt
    venv-create                            # Create virtual environment
    venv-export                            # Export the build environment to {{ env_export_file }}

Installing new packages

If you write documentation and find a useful extension or package to be added, use the uv add [packagename] command. Note that this will install the package only on your local devcontainer.

As long as you don't rebuild the container, you don't have to reinstall the package again.

Commit

Before commiting your work:

• Verify the build of the documentation locally:

  just clean && just serve # or through devcontainer
  

• Solve important build Warnings and Errors (if any) in the output.

• Check no temporary build / debug / cache files are staged for the commit.
• Commit and push your changes.
• Check that the pipeline is successful.

Continuous Integration(CI)

The pipelines will run on each main commit and create a public/ folder which will be used by gitlab pages and displayed as static html pages.