Skip to content

README.md

Latest commit

 

History

History
79 lines (47 loc) · 4.11 KB

README.md

File metadata and controls

79 lines (47 loc) · 4.11 KB
Raw

CI

Description of current CI workflow.

fetch_includes.yml

Retrieves dynamically generated content from external sources.

Currently retrieves:

  • Software module list from modules-list.

  • Glossary, spellcheck dictionary and snippets from nesi-wordlist

  • The training calendar and the software updates feed.

Runs daily at 00:00 UTC, and can be started manually. If anything changed (ignoring changes that are only to the calendar), the files are committed directly to main as nesi-mkdocs-bot ("Automatic asset update"), using the NESI_PAT secret. There is no intermediate branch.

The same script also runs at the start of every deploy, so the deployed site always uses the latest files.

compile_tags.py

Replaces the old link_apps_pages.py.

Validates page tags against the canonical vocabulary in docs/assets/tags.yml, writes two compiled indexes, and links app pages to the module list:

  • docs/assets/tag-index.json — maps each canonical tag to the list of pages that carry it. Used by the pages_with_tag() macro at render time.
  • docs/assets/module-list.json — updated with support-page URLs and canonical domain tags for each application.

Any tag not present in tags.yml (as a key or alias) produces a CI warning. Unknown tags are silently dropped from the index. An alias listed under more than one tag also produces a warning.

Runs in the Compile tags job of checks.yml and before every build in deploy.yml.

Tag vocabulary

Tags are defined in docs/assets/tags.yml. Each entry has a canonical key (snake_case), a display label, and optional aliases. Pages should always use canonical keys; aliases are accepted for backwards compatibility but are normalised at compile time.

checks.yml

A series of QA checks run on the documentation.

The checks can be started manually from the workflow page, select the target branch, give the pattern of files to include, and select which checks you want done.

Checks will also be run on every pull request. All checks will be run, but only on changed files (deleted files are left out).

Jobs: spelling, prose, markdownlint, page meta, Slurm scripts, accessibility (WCAG), compile tags, and a full test build (plus an ARIA reference check). Findings are reported as annotations. Only the test build and page meta jobs can fail, and only on errors.

The summary job collects every job's output into a single PR comment, see checks/README.md.

More info on what these checks do in README.md

deploy.yml

Runs on push to main branch, daily at 12:00 UTC, and manually. Fetches remote assets, compiles tags, builds the site and deploys it to GitHub Pages.

The rag-ingest job, which triggers a refresh of the docs search assistant index, is currently disabled (if: false).

demo_deploy.yml

Runs on every pull request (except from assets-update). Triggers a build of the branch in CallumWalley/mkdocs-demo-deploy, waits up to 10 minutes for it, then comments on the pull request with a link to the preview and to each changed page.

review_gate.yml

Required check. Passes if the PR only modifies existing docs/**/*.md files and changes 50 lines or fewer (MAX_LINES), or if someone other than the author has approved it. Bot PRs are exempt. A submitted or dismissed review re-runs the gate for the latest commit, so its check is replaced rather than duplicated. While the gate is failing, a comment on the PR explains why. It is deleted once the gate passes.

auto_merge.yml

Runs daily at 12:30 UTC, and manually. Squash-merges every open pull request with the auto_merge label, with no review. Only add the label to pull requests that should merge without review.