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 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:
Producing the following:
