simtools-docs-assemble-pages

Assemble a multi-version documentation site from released documentation builds.

Publishes all versions listed in a version switcher file (pydata-sphinx-theme format). Each version is downloaded as a tarball of its built HTML site (e.g., from the GitLab generic package registry) and extracted to <site_path>/<version>/; the newest version is also copied to the site root. Identical files are replaced by relative symlinks to a single copy, and the deployed size is checked against a size budget.

The GitLab CI job token is read from the CI_JOB_TOKEN environment variable.

Downloads the documentation builds of all versions listed in a version switcher file (--switcher_file) from --package_url (URL template with a {version} placeholder, e.g., the GitLab generic package registry) and assembles them into --site_path. The newest version is also served at the site root; identical files of different versions are stored once (relative symlinks). The application fails if the deployed size exceeds --size_budget_mb. With --validate_only, only the version switcher file is checked.

Example

simtools-docs-assemble-pages \\
    --switcher_file docs/_static/switcher.json \\
    --site_path public \\
    --package_url "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/docs/{version}/docs-site.tar.gz"

Command line arguments

options

–help

show this help message and exit

–switcher_file

Version switcher file listing the versions to publish.

Required.

–site_path

Directory of the assembled site (must be empty or not exist).

Default: public.

–package_url

URL template of the documentation tarballs with a ‘{version}’ placeholder.

–size_budget_mb

Maximum deployed size in MB.

Default: 1500.0.

–validate_only

Only validate the version switcher file.

application

–show_options

Print available values for a supported option and exit.

Example

Validate a documentation version switcher file

Check the list of documentation versions to publish (version switcher file of the pydata-sphinx-theme) without downloading or assembling the site.

Application: simtools-docs-assemble-pages

Integration test: docs_assemble_pages_validate.yml

Command

simtools-docs-assemble-pages --config tests/integration_tests/config/docs_assemble_pages_validate.yml

Configuration

switcher_file: docs/_static/switcher.json
validate_only: true