CHBH-on-BEAR Documentation

This documentation describes running CHBH-on-BEAR workflows on the University of Birmingham's BlueBEAR HPC system.

Contributors

Many thanks to our contributors - please open an issue if you're missing from this list.

ajquinn 🚧 🖋	James Carpenter 🚧 🖋	Brandon Ingram 🖋	Arkady Konovalov 🖋	Ben Griffiths 🖋	Tara 🖋	Dagmar S Fraser 🖋
Jianzhang Ni 🖋	Katharina 🖋	Tommy Roberts 🖋	Aamir Sohail 🚧 🖋	Selma Lugtmeijer 🖋

Publishing

The documentation is automatically built and published to https://chbh-opensource.github.io/chbh-on-bear on every push to the main branch of this repository.

This is taken care of by the deploy GitHub Actions workflow.

Using mkdocs

Creating a Development Environment and Installing mkdocs

To install all the required mkdocs Python packages, use the provided requirements.txt file. The recommendation for development is to do this inside a dedicated virtual environment:

git clone https://github.com/chbh-opensource/chbh-on-bear
cd chbh-on-bear
python -m venv ./.venv
source ./.venv/bin/activate
pip install -r requirements.txt

Building

To build the documentation, use:

mkdocs build

Testing

To test whether the documentation is building correctly, and whether all (internal) links are correct, use:

mkdocs build --strict

This command will exit with a non-zero exit code if mkdocs produces any errors or warnings.

Previewing

To see a local preview of the rendered documentation in your browser, use

mkdocs serve

and click the link that is provided, for example:

INFO     -  Documentation built in 0.24 seconds
INFO     -  [17:52:07] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [17:52:07] Serving on http://127.0.0.1:8000/

This preview of the rendered documentation will automatically refresh when the documentation sources are updated!

Making and committing changes

Once you have made your changes locally, get a summary by running:

git status

Then check if you have the CHBH-on-BEAR main branch as a remote:

git remote -v

Then, add your changes:

git add <file> # if making commits separately
git add . # if committing in one go

commit them:

git commit -m "your changes here'

and push them:

git push origin main

However, this will only work if you have write access to the main branch.

If you do not, then you will need to create a new branch, and then push the changes to the branch:

# after committing the changes
git checkout -b <your-branch-name>
git push origin <your-branch-name>

And then on GitHub, submit a pull request to the main branch!