UPPMAX / UPPMAX-documentation

http://docs.uppmax.uu.se
Other
5 stars 1 forks source link

UPPMAX Documentation

Check links Check markdown Check spelling Create website

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.