Contributing

Instructions for building on Nikhef machines

The documents are rendered with Sphinx which includes support for Markdown (c.q. CommonMark).

Sphinx translates from restructured text and/or markdown into html, epub, pdf and a few others. To add or contribute, go to gitlab.nikhef.nl and sign in using the “Federated login” button at the bottom right of page. Then browse to the repository at gitlab.nikhef.nl/roelaaij/computing-course, and fork it using the “Fork” button. Then clone your newly forked repository on a Nikhef machine:

$> git clone git@gitlab.nikhef.nl:your_username/computing-course

To build the site, create a_virtualenv with conda and install the dependencies

$> conda create /project/your_project/your_username/course_venv
$> conda activate /project/your_project/your_username/course_venv
(course_venv) $> conda install pip
(course_venv) $> cd /path/to/computing-course
(course_venv) $> pip install -r requirements.txt

Now you can edit the documentation. Any new files should be added to an index.rst file.

To build the site, and serve it to yourself, use.

(course_venv) $> make html
(course_venv) $> cd _build/html
(course_venv) $> python -m http.server

To then upstream your changes:

  • commit the changes

  • push to the fork on gitlab

  • submit a merge request

See the hsf-training guide on git if you need more information about using git.