From 283cd66a54ab87c2369863537226850b5bbd78ee Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Fri, 12 Jun 2026 16:25:59 +0100 Subject: [PATCH 01/17] Add banner to development docs to indicate version --- theme/header.hbs | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 theme/header.hbs diff --git a/theme/header.hbs b/theme/header.hbs new file mode 100644 index 000000000..1c33d448a --- /dev/null +++ b/theme/header.hbs @@ -0,0 +1,33 @@ + + +
+ This is the  development version  of the MUSE2 documentation. +
From 8a9a24a33db12810eb2dd70b56f982c0009a5e20 Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Tue, 16 Jun 2026 17:30:03 +0100 Subject: [PATCH 02/17] Include banner in old docs, use JS logic to determine colour --- docs/build_old_docs.py | 3 +++ theme/header.hbs | 23 +++++++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/docs/build_old_docs.py b/docs/build_old_docs.py index e5218d07f..48278f68a 100755 --- a/docs/build_old_docs.py +++ b/docs/build_old_docs.py @@ -72,6 +72,9 @@ def build_docs_for_release(release: str, repo_path: Path, outdir: Path) -> None: # Apply patches, if any apply_patches_for_release(release, release_path) + # Copy current theme into the release worktree so theme is consistent + shutil.copytree(REPO_ROOT / "theme", release_path / "theme", dirs_exist_ok=True) + # Build docs sp.run(("just", f"{release_path!s}/build-docs"), check=True) diff --git a/theme/header.hbs b/theme/header.hbs index 1c33d448a..6ad019e46 100644 --- a/theme/header.hbs +++ b/theme/header.hbs @@ -31,3 +31,26 @@
This is the  development version  of the MUSE2 documentation.
+ + From 3c135a92b89cd416cd612ba7821ba14a4678ffe9 Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Tue, 16 Jun 2026 17:44:42 +0100 Subject: [PATCH 03/17] Include a stable version of the docs --- docs/build_old_docs.py | 12 +++++++++--- docs/templates/versions.md.jinja | 1 + 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/build_old_docs.py b/docs/build_old_docs.py index 48278f68a..67911777e 100755 --- a/docs/build_old_docs.py +++ b/docs/build_old_docs.py @@ -64,7 +64,7 @@ def apply_patches_for_release(release: str, repo_path: Path) -> None: sp.run(("git", "-C", str(repo_path), "am", str(patch_path)), check=True) -def build_docs_for_release(release: str, repo_path: Path, outdir: Path) -> None: +def build_docs_for_release(release: str, repo_path: Path, outdir: Path) -> Path: """Build documentation for a given release.""" print(f"Building docs for {release}") release_path = add_worktree_for_release(repo_path, release) @@ -89,6 +89,8 @@ def build_docs_for_release(release: str, repo_path: Path, outdir: Path) -> None: print(f"Copying to {release_outdir}") shutil.move((release_path / "book"), release_outdir) + return release_outdir + def build_old_docs() -> None: """Build documentation for previous releases.""" @@ -101,8 +103,12 @@ def build_old_docs() -> None: clone_repo_to(repo_path) # Generate documentation for each previous release - for release in get_releases(): - build_docs_for_release(release, repo_path, outdir) + for i, release in enumerate(get_releases()): + release_outdir = build_docs_for_release(release, repo_path, outdir) + + # Copy latest release into stable dir + if i == 0: + shutil.copytree(release_outdir, outdir / "stable") if __name__ == "__main__": diff --git a/docs/templates/versions.md.jinja b/docs/templates/versions.md.jinja index 6e5a84c64..838a91c0c 100644 --- a/docs/templates/versions.md.jinja +++ b/docs/templates/versions.md.jinja @@ -3,6 +3,7 @@ The MUSE2 documentation for different releases is available below. - [Current development version](index.html) +- [Stable version](release/stable/index.html) {%- for release in releases %} - [{{ release }}](release/{{ release }}/index.html) {%- endfor %} From 805bb8b04b5cfbc836e06b808ae60f33814b00be Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Tue, 16 Jun 2026 17:55:20 +0100 Subject: [PATCH 04/17] Do not show a banner for the stable version --- theme/header.hbs | 60 ++++++++++++++++++++++++------------------------ 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/theme/header.hbs b/theme/header.hbs index 6ad019e46..eadd25137 100644 --- a/theme/header.hbs +++ b/theme/header.hbs @@ -2,55 +2,55 @@ :root { --banner-height: 36px; } #version-banner { + display: none; position: fixed; top: 0; left: 0; right: 0; height: var(--banner-height); z-index: 9999; - display: flex; align-items: center; justify-content: center; font-size: 0.875em; box-sizing: border-box; padding: 0 16px; - background-color: #fff3cd; - border-bottom: 1px solid #ffc107; - } - - #version-banner, #version-banner * { - color: #664d03 !important; - } - - body { padding-top: var(--banner-height); } - #mdbook-menu-bar.sticky { top: var(--banner-height) !important; } - #mdbook-sidebar { - top: var(--banner-height) !important; - height: calc(100vh - var(--banner-height)) !important; } -
- This is the  development version  of the MUSE2 documentation. -
+
From ba5426db9af7c1bbed0c4494244559a2d211a2c1 Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Thu, 18 Jun 2026 15:32:52 +0100 Subject: [PATCH 05/17] Remove stable directory before creating it new Assisted-by: Copilot Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/build_old_docs.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/build_old_docs.py b/docs/build_old_docs.py index 67911777e..e988f150d 100755 --- a/docs/build_old_docs.py +++ b/docs/build_old_docs.py @@ -108,7 +108,9 @@ def build_old_docs() -> None: # Copy latest release into stable dir if i == 0: - shutil.copytree(release_outdir, outdir / "stable") + stable_dir = outdir / "stable" + shutil.rmtree(stable_dir, ignore_errors=True) + shutil.copytree(release_outdir, stable_dir) if __name__ == "__main__": From e22f79c9a2df0f5e7e36ab01675bf03d56f95e09 Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Thu, 18 Jun 2026 15:37:10 +0100 Subject: [PATCH 06/17] Use ARIA semantics for live-updated banner Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- theme/header.hbs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/theme/header.hbs b/theme/header.hbs index eadd25137..7063a5a77 100644 --- a/theme/header.hbs +++ b/theme/header.hbs @@ -15,7 +15,7 @@ } -
+
From 80391b7c13fd0646889278c50190e0609f7fc9f1 Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Wed, 17 Jun 2026 18:06:00 +0100 Subject: [PATCH 08/17] Add version selector widget. Generate theme to get list of versions --- build-docs.just | 7 +- docs/generate_header.py | 27 +++++ docs/templates/header.hbs.jinja | 173 ++++++++++++++++++++++++++++++++ theme/.gitignore | 2 + 4 files changed, 208 insertions(+), 1 deletion(-) create mode 100644 docs/generate_header.py create mode 100644 docs/templates/header.hbs.jinja create mode 100644 theme/.gitignore diff --git a/build-docs.just b/build-docs.just index 1a5cf67cd..2e1adb1e1 100644 --- a/build-docs.just +++ b/build-docs.just @@ -2,7 +2,7 @@ export RUSTDOCFLAGS := "-D warnings" # Build all documentation, except old docs -all: cli-help file-format examples versions book api +all: cli-help file-format examples versions header book api # Build all documentation, including old docs all_with_old: all old @@ -42,6 +42,11 @@ versions: @echo Building TOC for old versions of documentation @uv run docs/generate_versions_docs.py +# Generate theme file for version banner and widget for docs +header: + @echo Generating theme/header.hbs + @uv run docs/generate_header.py + # Build documentation for previous releases old: @# Clean output dir diff --git a/docs/generate_header.py b/docs/generate_header.py new file mode 100644 index 000000000..eb9d8312d --- /dev/null +++ b/docs/generate_header.py @@ -0,0 +1,27 @@ +#!/usr/bin/env python3 +# +# A script to generate theme/header.hbs from a Jinja2 template. + +from pathlib import Path + +from jinja2 import Environment, FileSystemLoader +from release import get_releases + +DOCS_DIR = Path(__file__).parent.absolute() +REPO_ROOT = DOCS_DIR.parent + + +def generate_header_hbs() -> None: + """Write the theme/header.hbs file.""" + path = REPO_ROOT / "theme" / "header.hbs" + print(f"Writing {path}") + env = Environment(loader=FileSystemLoader(DOCS_DIR / "templates")) + template = env.get_template("header.hbs.jinja") + out = template.render(releases=get_releases()) + + with path.open("w", encoding="utf-8") as f: + f.write(out) + + +if __name__ == "__main__": + generate_header_hbs() diff --git a/docs/templates/header.hbs.jinja b/docs/templates/header.hbs.jinja new file mode 100644 index 000000000..7dd768738 --- /dev/null +++ b/docs/templates/header.hbs.jinja @@ -0,0 +1,173 @@ + + +
+ +
+
    + docs: ▲ +
    + + diff --git a/theme/.gitignore b/theme/.gitignore new file mode 100644 index 000000000..7affc7289 --- /dev/null +++ b/theme/.gitignore @@ -0,0 +1,2 @@ +# Generated documentation theme file +header.hbs From 707848d41d1faf7ad7c0ffc0b82fd286dac4945b Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Wed, 17 Jun 2026 18:59:07 +0100 Subject: [PATCH 09/17] Remove other versions docs from contents --- docs/SUMMARY.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 38e092116..36f0c2ee3 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -25,4 +25,3 @@ - [MUSE2 v2.0.0 (October 14, 2025)](release_notes/v2.0.0.md) - [MUSE2 v2.1.0 (March 31, 2026)](release_notes/v2.1.0.md) - [Next unreleased version](release_notes/upcoming.md) -- [Other versions of documentation](versions.md) From a11b5eaefc0025f9fa996e98501897b3d86a8c03 Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Wed, 17 Jun 2026 19:05:36 +0100 Subject: [PATCH 10/17] Remove the 'other versions' section. Superseeded by widget --- build-docs.just | 7 +---- docs/.gitignore | 1 - docs/build_old_docs.py | 6 ----- docs/generate_versions_docs.py | 26 ------------------- ...older-other-versions-of-docs-chapter.patch | 21 --------------- ...ve-other-versions-docs-from-contents.patch | 20 ++++++++++++++ docs/templates/versions.md.jinja | 9 ------- 7 files changed, 21 insertions(+), 69 deletions(-) delete mode 100644 docs/generate_versions_docs.py delete mode 100644 docs/release/patches/v2.0.0/0002-Add-placeholder-other-versions-of-docs-chapter.patch create mode 100644 docs/release/patches/v2.1.0/0001-Remove-other-versions-docs-from-contents.patch delete mode 100644 docs/templates/versions.md.jinja diff --git a/build-docs.just b/build-docs.just index 2e1adb1e1..078603a12 100644 --- a/build-docs.just +++ b/build-docs.just @@ -2,7 +2,7 @@ export RUSTDOCFLAGS := "-D warnings" # Build all documentation, except old docs -all: cli-help file-format examples versions header book api +all: cli-help file-format examples header book api # Build all documentation, including old docs all_with_old: all old @@ -37,11 +37,6 @@ examples: @echo Building docs for examples @uv run docs/generate_example_docs.py -# Build TOC for old versions -versions: - @echo Building TOC for old versions of documentation - @uv run docs/generate_versions_docs.py - # Generate theme file for version banner and widget for docs header: @echo Generating theme/header.hbs diff --git a/docs/.gitignore b/docs/.gitignore index 9eece75fc..ab9fc47fa 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,4 +1,3 @@ # Generated documentation files command_line_help.md examples.md -versions.md diff --git a/docs/build_old_docs.py b/docs/build_old_docs.py index e988f150d..ece8841ce 100755 --- a/docs/build_old_docs.py +++ b/docs/build_old_docs.py @@ -78,12 +78,6 @@ def build_docs_for_release(release: str, repo_path: Path, outdir: Path) -> Path: # Build docs sp.run(("just", f"{release_path!s}/build-docs"), check=True) - # Patch versions.html to redirect to main versions page - with (release_path / "book" / "versions.html").open("w", encoding="utf-8") as f: - f.write(f""" - -""") - # Move to output directory release_outdir = outdir / release print(f"Copying to {release_outdir}") diff --git a/docs/generate_versions_docs.py b/docs/generate_versions_docs.py deleted file mode 100644 index 9211ecd76..000000000 --- a/docs/generate_versions_docs.py +++ /dev/null @@ -1,26 +0,0 @@ -#!/usr/bin/env python3 -# -# A script to generate the versions.md file, listing links to old versions of documentation. - -from pathlib import Path - -from jinja2 import Environment, FileSystemLoader -from release import get_releases - -DOCS_DIR = Path(__file__).parent.absolute() - - -def generate_versions_md() -> None: - """Write the versions.md file.""" - path = DOCS_DIR / "versions.md" - print(f"Writing {path}") - env = Environment(loader=FileSystemLoader(DOCS_DIR / "templates")) - template = env.get_template("versions.md.jinja") - out = template.render(releases=get_releases()) - - with path.open("w", encoding="utf-8") as f: - f.write(out) - - -if __name__ == "__main__": - generate_versions_md() diff --git a/docs/release/patches/v2.0.0/0002-Add-placeholder-other-versions-of-docs-chapter.patch b/docs/release/patches/v2.0.0/0002-Add-placeholder-other-versions-of-docs-chapter.patch deleted file mode 100644 index a4658d9e2..000000000 --- a/docs/release/patches/v2.0.0/0002-Add-placeholder-other-versions-of-docs-chapter.patch +++ /dev/null @@ -1,21 +0,0 @@ -From e0638c6639a5ce322977cafdb4d06b656cd77cb7 Mon Sep 17 00:00:00 2001 -From: Alex Dewar -Date: Wed, 29 Apr 2026 14:43:12 +0100 -Subject: [PATCH] Add placeholder "other versions of docs" chapter - -This will redirect to the version in the main version of the docs when built. ---- - docs/SUMMARY.md | 1 + - 1 file changed, 1 insertion(+) - -diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md -index 5a1d47bf..ab00b928 100644 ---- a/docs/SUMMARY.md -+++ b/docs/SUMMARY.md -@@ -15,3 +15,4 @@ - - [Model Diagrams](model/model_diagrams.md) - - [Glossary](glossary.md) - - [Developer Guide](developer_guide.md) -+- [Other versions of documentation](versions.md) --- -2.54.0 diff --git a/docs/release/patches/v2.1.0/0001-Remove-other-versions-docs-from-contents.patch b/docs/release/patches/v2.1.0/0001-Remove-other-versions-docs-from-contents.patch new file mode 100644 index 000000000..2ab4d977d --- /dev/null +++ b/docs/release/patches/v2.1.0/0001-Remove-other-versions-docs-from-contents.patch @@ -0,0 +1,20 @@ +From 2ee8d44b2c4a6b3b2e5ed1a546a3dd6ac2c20dab Mon Sep 17 00:00:00 2001 +From: Adrian D'Alessandro +Date: Wed, 17 Jun 2026 18:59:07 +0100 +Subject: [PATCH] Remove other versions docs from contents + +--- + docs/SUMMARY.md | 1 - + 1 file changed, 1 deletion(-) + +diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md +index 38e09211..36f0c2ee 100644 +--- a/docs/SUMMARY.md ++++ b/docs/SUMMARY.md +@@ -25,4 +25,3 @@ + - [MUSE2 v2.0.0 (October 14, 2025)](release_notes/v2.0.0.md) + - [MUSE2 v2.1.0 (March 31, 2026)](release_notes/v2.1.0.md) + - [Next unreleased version](release_notes/upcoming.md) +-- [Other versions of documentation](versions.md) +-- +2.50.1 (Apple Git-155) diff --git a/docs/templates/versions.md.jinja b/docs/templates/versions.md.jinja deleted file mode 100644 index 838a91c0c..000000000 --- a/docs/templates/versions.md.jinja +++ /dev/null @@ -1,9 +0,0 @@ -# Other versions of documentation - -The MUSE2 documentation for different releases is available below. - -- [Current development version](index.html) -- [Stable version](release/stable/index.html) -{%- for release in releases %} -- [{{ release }}](release/{{ release }}/index.html) -{%- endfor %} From ddf9c11420839ae85e0937815e63635e29dece08 Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Thu, 18 Jun 2026 16:02:01 +0100 Subject: [PATCH 11/17] Add some aria labels --- docs/templates/header.hbs.jinja | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/templates/header.hbs.jinja b/docs/templates/header.hbs.jinja index 7dd768738..0c36e21cb 100644 --- a/docs/templates/header.hbs.jinja +++ b/docs/templates/header.hbs.jinja @@ -77,10 +77,10 @@ } -
    +
    -
      +
        docs: ▲
        From 319405f4ea14603a6dce1c49c34060a4236f26ca Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Tue, 23 Jun 2026 12:02:37 +0100 Subject: [PATCH 12/17] Apply JS best-practice suggestions Assisted-by: Copilot Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/templates/header.hbs.jinja | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/templates/header.hbs.jinja b/docs/templates/header.hbs.jinja index 0c36e21cb..94304540f 100644 --- a/docs/templates/header.hbs.jinja +++ b/docs/templates/header.hbs.jinja @@ -39,8 +39,7 @@ color: #fff; padding: 6px 12px; border-radius: 4px 4px 0 0; - cursor: default; - user-select: none; + cursor: pointer; } #version-arrow { @@ -80,8 +79,8 @@
        -
          - docs: ▲ +
            + docs: ▲