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

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

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

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

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.

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