How to contribute to the Run 3 Starterkit

Listed here are the instructions for how to contribute to the Run 3 Starterkit, thank you for thinking about contributing!

Minor edits

To make a minor edit to a pre-existing lesson (fixing a broken link, spelling mistake etc), it's enough just to click to 'edit this page' button on the lesson (the pencil). This will take you directly to GitLab where the edit can be made and committed.

More major edits

In general, to make a larger change to the lessons, start by cloning the repository.

git clone ssh://git@gitlab.cern.ch:7999/lhcb-dpa/wp7-training-and-documenation/starterkit-run3.git 

Following that, any changes made may be committed to a branch as normal and a merge request may be opened.

To make a local build of the Starterkit to see how your changes will look in the final product, you may use the included build.sh script. After which the file public/index.html may be opened following the instructions below.

Run in a venv

To run this in a virtual environment you can first do conda env create -f environment.yml. But this does not guarantee replicating how the CI will build it.

The lessons are stored in the doc folder with a hierarchy following that of the lessons/sub-lessons in the Starterkit. To edit a preexisting lesson it is enough to find its .en.md file and make edits there directly.

Opening the local docs

Once the docs are built, if they are built on your local machine, they may be opened by running the following.

If the docs have been built locally, it should be enough to run:

python -m mkdocs serve
# Now navigate to http://127.0.0.1:8000/

If they are not built locally, the best approach is to copy the public folder locally and then run the below:

cd public
python -m http.server 8000 & # Remember to kill this after closing the webpage!
export serverjob=$!
python -m webbrowser http://[::]:8000/

The server can then be later killed by running kill $serverjob

Adding new lessons

To add a new lesson, make a .en.md file for it in doc following the directory structure. By default the lesson name will be the same as its filename, if you want to change this it can be done in mkdocs.yml.

Adding testable codeblocks

Adding codeblocks may be done in the usual "markdown" way with triple backticks ```, however for any major changes to the code it's better to add tests ensuring that the code will continue to work for future readers of the Starterkit.

This is done in three steps:

1. Add the testable code to the docs/<x>-analysis-steps/code/<lesson> folder.
   • You may only need a subset of this file to be included in the actual lesson, but the code in the code/<lesson> folder needs to be able to run.
2. Write a test in testing/<x>-analysis-steps to run the code from step 1, this is done in the format of a pytest and will be automatically picked up by the Gitlab CI.
3. Add the snippet into the lesson with the following syntax:

--8<-- "docs/<x>-analysis-steps/code/<lesson>/filename.py"

For more specific additions (e.g. adding just sections of the code), check the pymdownx documentation.

Adding images

To add an image, place it next to the lesson in a folder - by convention called img, and then they may be added as:

![Starterkit logo](img/starterkit.png)

Producing the following: