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 🖋	TomRhysMarshall 🖋	Nicholas Paul Holmes 🖋
Martin Wilson 🖋	froemero 🖋

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

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:

The following steps are platform dependent. Please follow the appropriate instructions for your platform (mac/linux, or windows).

Creating a Development Environment and Installing mkdocs - MAC/LINUX

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

Creating a Development Environment and Installing mkdocs - WINDOWS

Windows users will need to do a few extra steps:

Open Windows PowerShell (click Windows button and type 'powershell')

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Change directory to the place you want to work in and clone the repository

cd <my working directory>
git clone https://github.com/chbh-opensource/chbh-on-bear

Create and activate virtual environment

cd chbh-on-bear
uv venv --python 3.11
Set-ExecutionPolicy Unrestricted -Scope Process
cd .venv\Scripts
.\activate.ps1
cd ..
cd ..
uv pip install -r requirements.txt

The subsequent steps are the same regardless of platform

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

add your changes:

git add <file> # if adding files separately
git add . # if adding all changes in one go

commit:

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, where one of the maintainers will have a look!