diff --git a/docs/build_old_docs.py b/docs/build_old_docs.py
index 71fa35ae2..e5218d07f 100755
--- a/docs/build_old_docs.py
+++ b/docs/build_old_docs.py
@@ -16,13 +16,37 @@
def clone_repo_to(dest: Path):
- """Clone this repo somewhere else."""
- print("Making a copy of repo")
- sp.run(("git", "clone", REPO_ROOT, dest), check=True, capture_output=True)
+ """Make a bare clone of this repo somewhere else."""
+ print(f"Making a copy of repo in {dest}")
+ sp.run(("git", "clone", "--bare", REPO_ROOT, dest), check=True, capture_output=True)
+
+
+def add_worktree_for_release(repo_path: Path, release: str) -> Path:
+ """Add a worktree for the current release.
+
+ Also tries to symlink to the cargo cache dir to speed up build times, if possible.
+ """
+ # Add new worktree
+ release_path = repo_path.parent / release
+ sp.run(
+ (
+ "git",
+ "-C",
+ str(repo_path),
+ "worktree",
+ "add",
+ release_path,
+ release,
+ ),
+ check=True,
+ capture_output=True,
+ )
# Add a symlink to cargo cache dir
try:
- os.symlink(REPO_ROOT / "target", dest / "target")
+ os.symlink(
+ REPO_ROOT / "target", release_path / "target", target_is_directory=True
+ )
except (NotImplementedError, OSError):
# Only newer versions of Windows support symlinks and these require the user to have
# additional privileges (or to be in developer mode)
@@ -30,6 +54,8 @@ def clone_repo_to(dest: Path):
"WARN: Could not create symlink to cache directory; cache will not be stored"
)
+ return release_path
+
def apply_patches_for_release(release: str, repo_path: Path) -> None:
"""Apply patches (if any) for the given release."""
@@ -41,22 +67,16 @@ def apply_patches_for_release(release: str, repo_path: Path) -> None:
def build_docs_for_release(release: str, repo_path: Path, outdir: Path) -> None:
"""Build documentation for a given release."""
print(f"Building docs for {release}")
-
- # Check out release
- sp.run(
- ("git", "-C", str(repo_path), "checkout", release),
- check=True,
- capture_output=True,
- )
+ release_path = add_worktree_for_release(repo_path, release)
# Apply patches, if any
- apply_patches_for_release(release, repo_path)
+ apply_patches_for_release(release, release_path)
# Build docs
- sp.run(("just", f"{repo_path!s}/build-docs"), check=True)
+ sp.run(("just", f"{release_path!s}/build-docs"), check=True)
# Patch versions.html to redirect to main versions page
- with (repo_path / "book" / "versions.html").open("w", encoding="utf-8") as f:
+ with (release_path / "book" / "versions.html").open("w", encoding="utf-8") as f:
f.write(f"""
""")
@@ -64,7 +84,7 @@ def build_docs_for_release(release: str, repo_path: Path, outdir: Path) -> None:
# Move to output directory
release_outdir = outdir / release
print(f"Copying to {release_outdir}")
- shutil.move((repo_path / "book"), release_outdir)
+ shutil.move((release_path / "book"), release_outdir)
def build_old_docs() -> None:
@@ -74,7 +94,7 @@ def build_old_docs() -> None:
# Clone this repo to a temporary directory
with TemporaryDirectory() as tmpdir:
- repo_path = Path(tmpdir)
+ repo_path = Path(tmpdir) / "MUSE2.git"
clone_repo_to(repo_path)
# Generate documentation for each previous release
diff --git a/docs/release/__init__.py b/docs/release/__init__.py
index f2505b426..39c4ab640 100644
--- a/docs/release/__init__.py
+++ b/docs/release/__init__.py
@@ -2,6 +2,7 @@
import re
import subprocess as sp
+from pathlib import Path
def is_release_tag(tag: str) -> bool:
@@ -14,8 +15,10 @@ def is_release_tag(tag: str) -> bool:
def get_releases() -> list[str]:
"""Get all release tags for this repo, sorted by semantic version."""
+
+ repo_path = Path(__file__).parent
ret = sp.run(
- ("git", "tag", "-l", "--sort=-version:refname"),
+ ("git", "-C", str(repo_path), "tag", "-l", "--sort=-version:refname"),
capture_output=True,
check=True,
encoding="utf-8",
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
new file mode 100644
index 000000000..a4658d9e2
--- /dev/null
+++ b/docs/release/patches/v2.0.0/0002-Add-placeholder-other-versions-of-docs-chapter.patch
@@ -0,0 +1,21 @@
+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