From 9f61cdf5ae3d7664f0a12dfdb67ffdc77018873e Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Wed, 17 Jun 2026 18:04:45 +0100 Subject: [PATCH 1/5] Remove theme header becasue it will be generated --- theme/header.hbs | 56 ------------------------------------------------ 1 file changed, 56 deletions(-) delete mode 100644 theme/header.hbs diff --git a/theme/header.hbs b/theme/header.hbs deleted file mode 100644 index 7063a5a77..000000000 --- a/theme/header.hbs +++ /dev/null @@ -1,56 +0,0 @@ - - -
- - From 0027c4db1d822211d8e2d30abcce975a4ea108fa Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Wed, 17 Jun 2026 18:06:00 +0100 Subject: [PATCH 2/5] 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 1059091c975b69c116573adcfb1516764d6d48b7 Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Wed, 17 Jun 2026 18:59:07 +0100 Subject: [PATCH 3/5] 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 17d6346e2679c24b063e63b3236b842baa61bf74 Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Wed, 17 Jun 2026 19:05:36 +0100 Subject: [PATCH 4/5] 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 e1f950e5c5cee3db537efbba6245a969b781a1d4 Mon Sep 17 00:00:00 2001 From: Adrian D'Alessandro Date: Thu, 18 Jun 2026 16:02:01 +0100 Subject: [PATCH 5/5] 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: ▲