UPPMAX Documentation

This repository contains the source code for the UPPMAX documentation

Branch descriptions

Branch name	Description
main	The main branch, runs all CI scripts
develop	A develop branch, does not spellcheck, does not deploy the website
issue_x	A branch named after an Issue, does not spellcheck, does not deploy the website
gh-pages	The GitHub Pages branch, maintained by GitHub Actions

Contributing

See CONTRIBUTING.md.

Working on the documentation locally

To work on the website locally first create a virtual environment and install the required dependencies

python3 -m venv uppmax_venv
source uppmax_venv/bin/activate
pip install -r requirements.txt

Then activate the environment and serve the website on localhost

mkdocs serve

Optional dependencies

Software table

Dependencies:

pip install natsort

The software table is generated on each deploy on GitHub actions, so you have to do that manually if you want to view it locally:

./scripts/create_software_table.sh

Text-to-speech

Dependencies:

pip install beautifulsoup4\>=4.11.1 gTTS\>=2.2.4

The script md_to_speech.py takes an .md file, parses the text and generates an mp3 using gTTS. Run it by

python3 scripts/md_to_speech.py --input txt.md --lang en

Files used by continuous integration scripts

Filename	Descriptions
mlc_config.json	Configuration of the link checker, use markdown-link-check --config mlc_config.json --quiet docs/**/*.md to do link checking locally
.spellcheck.yml	Configuration of the spell checker, use pyspelling -c .spellcheck.yml to do spellcheck locally
.wordlist.txt	Whitelisted words for the spell checker, use pyspelling -c .spellcheck.yml to do spellcheck locally
.markdownlint.jsonc	Configuration of the markdown linter, use markdownlint "**/*.md" to do markdown linting locally. The name of this file is a default name.
.markdownlintignore	Files ignored by the markdown linter, use markdownlint "**/*.md" to do markdown linting locally. The name of this file is a default name.

Credits

The website is created using mkdocs-material. The landing page and layout was inspired by the documentation of the HPC cluster LUMI.