Documentation hub of the ELIXIR On-Cloud federated deployment: guides for architects and operators, partners and developers, and researchers. Built with MkDocs Material and published on Read the Docs.
Read the documentation at https://docs.elixir-on.cloud/.
Install the dependencies in a virtual environment, check the spelling of the project names, and build the site (warnings fail the build):
python -m venv .venv
source .venv/bin/activate
pip install -e ".[docs,tests]"
python scripts/check_names.py
mkdocs build --strict
pytestTo preview the site while you edit, run mkdocs serve.
The strict build checks the links between pages. External links are checked
weekly by the Links workflow, which opens an
issue "Dead links in the docs" when it finds any. To run the same check
locally, install lychee and run:
lychee --config lychee.toml "docs/**/*.md" "includes/*.md" README.mdSet GITHUB_TOKEN to any token first to avoid GitHub's rate limits.
The same workflow checks the GA4GH service URLs in the docs (URLs with
/ga4gh/<api>/v<n>) and opens an issue "Service URLs in the docs" if a
service is not in the Cloud Registry
or does not answer GET <url>/service-info. All four checks of the
workflow (links, services, archived repositories and last verified
dates, below) run every Monday and can be started
by hand (gh workflow run links.yml); they run only in the
elixir-cloud-aai organization, not in forks, and are not required
checks of pull requests. While a problem persists, each run
comments on the open issue. To run the service check locally:
python scripts/check_services.pyIt checks README.md, docs and includes (or the paths you pass)
against the registry of extra.registry_url in mkdocs.yml (or
--registry URL); --output FILE also writes the report to a file, and
--help lists all options. It exits with 0 if all services are fine, 2 if
it found problems and 1 if it could not run (e.g. the registry is down or
the configuration is invalid). Placeholders and local hosts such as
example.org, <HOST>, localhost, in-cluster names and private
addresses are skipped. Configure the rest in
service-check.toml:
skip_hosts: public third-party services (e.g. WorkflowHub), which are not ours to register.unregistered: our services that pages still name but that are not registered yet, each with the reason. They must still answerservice-info. The check reports an entry once the service is registered or no page names it any more, so remove it then.
Prefer linking to a service's registry entry over naming its address; a new address in the docs needs a registry entry first.
The third job reports links to archived repositories of the
organization (github.com/elixir-cloud-aai/<repo>, also SSH clone URLs
and raw.githubusercontent.com) in Markdown, YAML, JSON and shell files,
in an issue "Links to archived repositories in the docs". It asks the
GitHub API which repositories are archived, so the list is never out of
date. Remove such a link, point it to the successor, or, where the page
deliberately talks about the past (e.g. retired demos), mark it with an
HTML comment on the same line or alone on the line above (above reference
definitions, which can't take one on their line; in YAML and shell files
as a comment, # <!-- historical -->; JSON files can't take one, so
remove or replace links there). A marker covers every link on its line,
or on the next line if it stands alone:
- [Crypt4GH middleware](https://github.com/elixir-cloud-aai/protes-middleware-crypt4gh) (archived) <!-- historical -->
<!-- historical -->
[repo-workflows]: <https://github.com/elixir-cloud-aai/demo-workflows>To run the check locally (it checks README.md, mkdocs.yml, docs and
includes, or the paths you pass; exit codes as above):
python scripts/check_archived.pySet GITHUB_TOKEN to any token first to avoid GitHub's rate limits.
Tables of the deployed services are not written by hand: the hook
hooks/registry.py fetches them from the
Cloud Registry on
every build. To add a table to a page, put a marker on a line of its own,
e.g.:
<!-- registry:services -->
<!-- registry:services type=tes -->
<!-- registry:services type=tes,wes environment=all -->type: comma-separated service types (thetype.artifactof the service, e.g.tes,wes); all types if left out.environment:prod(default),test, any other environment of the registry, orall. Services without an environment are listed only withall.
A marker may be indented, e.g. inside an admonition or a tab; the table gets the same indentation. Markers in fenced code blocks are left alone, so pages can show the syntax there (not in indented code blocks, where markers are replaced).
The table lists name, organization, type and API version, service version,
environment, URL and docs link of each matching service. The registry is
set by extra.registry_url in mkdocs.yml; forks can point it to their
own registry.
The build needs network access to the registry and fails if the
registry can't be reached or answers with something that isn't a list of
services, so the site never shows stale data. This applies to the Docs
job of CI and to Read the Docs too: if the registry is down, re-run the
job once it is back. For local builds and previews without network
access, render a warning in place of each table instead:
DOCS_REGISTRY_OFFLINE=1 mkdocs build --strict
DOCS_REGISTRY_OFFLINE=1 mkdocs serveThe hook refuses DOCS_REGISTRY_OFFLINE=1 in CI and on Read the Docs
(where CI or READTHEDOCS is set), so published builds always show
the services.
Pages with operational facts that can't be generated, such as onboarding
steps, access procedures, addresses, versions and contacts, say when
someone last checked those facts against their sources. Their front matter
holds the date, which the page shows at its end (see
overrides/partials/content.html):
---
last_verified: 2026-11-17
----
Set the date (
YYYY-MM-DD) only after you have checked every operational fact of the page against its source: the Cloud Registry, the repository and docs of the product, or the live service. Fix what is wrong in the same pull request. -
last_verified: nullmarks a page with operational facts that nobody has verified yet; the page says "Facts not verified yet". -
Which pages carry the key: the operator pages (
docs/operators/), the researchers' start page and guides, the tutorial on interactive services (tutorials/tes-services/), the API guide (partners-and-developers/apis.md), the demos index and About. Give new pages with operational facts the key too, withnulluntil you have verified them. This is a convention: the build doesn't require the key. -
Editing a page doesn't change its date, but check every operational fact that you add or change against its source, as for any change of the docs. A pull request that sets a date verifies the page as it is on
mainwhen it merges: update its branch first, and check what changed. -
Anything else than an unquoted date or
nullfails the build (hookhooks/last_verified.py). Write the key unquoted, once, at the top level of the front matter, with its value on the same line, as above: the weekly check below can't read other forms and fails on them, and on dates in the future. -
Every Monday, the
Linksworkflow lists the pages whose date is older than 6 months or stillnullin an issue "Docs pages to verify", and comments on it while pages are due; unlike the other checks, due pages don't fail the run. Verify them, or remove the key from pages that no longer hold operational facts. Close the issue once no page is due; the next run that finds one opens a new issue. To list them locally (--months Nsets another maximum age,--helplists all options; exit codes as for the checks above, 1 also for a malformed date):python scripts/check_verified.py
-
The partial is a copy of Material's: when you upgrade Material, compare it with the new release's
partials/content.html.
Contributions are welcome! See the organisation's contributing guide and mind our code of conduct.
The content is licensed under Creative Commons Zero, version 1.0 (CC0).