Setup

The following page will help you set up your working environment to perform changes on the OpenRAMAN project. It includes information on where to obtain the source files for the hardware, software and documentation and how to configure the various tools that we use for the project.

Obtaining the sources

All our software, hardware and documentation are stored in git repositories where the masters can be found on our website at https://git.thepulsar.be/. Please note that we do not use external repository services like GitHub or GitLab and kindly ask you not to encourage this practice as it can throw confusion in other users mind.

For Windows users, git can be obtained either from the git official website or via the powershell by typing the command

    winget install --id Git.Git -e --source winget

For Debian Linux users, use the apt command

    sudo apt update
    sudo apt upgrade
    sudo apt install git

Once configured, you can retrieve a copy of the master repository using the git clone command:

Setting up GCC and Visual Studio

For users who wish to contribute to the software, we ask that their changes be validated on both Windows and Debian Linux platforms.

On Windows, we use Visual Studio which provides, at the time of this writting, a free version for non-commercial projects sur as ours. On Linux, we use GCC and Make which can be installed using

    sudo apt update
    sudo apt upgrade
    sudo apt install g++ make build-essentials

Setting up MkDocs

The documentation files are written in Markdown language. Markdown is a human-readable markup language designed at generating documentation as .html files. You do not need to generate the HTML yourself as we take this step when we will publish your changes to the website. Instead, you should only modify .md files and .yml files.

More specifically, we use the Material, Pymdown and Minify extensions of the markdown language which you will need to install as well.

For Debian users, or Windows users who run the Debian WSL, install mkdocs using

    sudo apt update
    sudo apt upgrade
    sudo apt install python3 python3-pip

    python3 -m venv venv
    source venv/bin/activate

    pip install -r requirements.txt

To visualize your changes to .md files, you need to run the command mkdocs serve --livereload in the folder where you cloned the repository. For Windows users under WSL, things are a bit different because you may need to run a virtual environment to execute mkdocs properly in case it fails to load the various required extensions:

    source venv/bin/activate
    python -m mkdocs serve --livereload