Skip to content

Commit 44f33be

Browse files
alexdewaralexdewar
authored
Merge pull request #1308 from EnergySystemsModellingLab/other-docs-in-v2
Show "other versions of documentation" link in v2.0.0 docs and other tweaks
2 parents 9cbad5e + 08396bc commit 44f33be

3 files changed

Lines changed: 61 additions & 17 deletions

File tree

‎docs/build_old_docs.py‎

Lines changed: 36 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -16,20 +16,46 @@
1616

1717

1818
def clone_repo_to(dest: Path):
19-
"""Clone this repo somewhere else."""
20-
print("Making a copy of repo")
21-
sp.run(("git", "clone", REPO_ROOT, dest), check=True, capture_output=True)
19+
"""Make a bare clone of this repo somewhere else."""
20+
print(f"Making a copy of repo in {dest}")
21+
sp.run(("git", "clone", "--bare", REPO_ROOT, dest), check=True, capture_output=True)
22+
23+
24+
def add_worktree_for_release(repo_path: Path, release: str) -> Path:
25+
"""Add a worktree for the current release.
26+
27+
Also tries to symlink to the cargo cache dir to speed up build times, if possible.
28+
"""
29+
# Add new worktree
30+
release_path = repo_path.parent / release
31+
sp.run(
32+
(
33+
"git",
34+
"-C",
35+
str(repo_path),
36+
"worktree",
37+
"add",
38+
release_path,
39+
release,
40+
),
41+
check=True,
42+
capture_output=True,
43+
)
2244

2345
# Add a symlink to cargo cache dir
2446
try:
25-
os.symlink(REPO_ROOT / "target", dest / "target")
47+
os.symlink(
48+
REPO_ROOT / "target", release_path / "target", target_is_directory=True
49+
)
2650
except (NotImplementedError, OSError):
2751
# Only newer versions of Windows support symlinks and these require the user to have
2852
# additional privileges (or to be in developer mode)
2953
print(
3054
"WARN: Could not create symlink to cache directory; cache will not be stored"
3155
)
3256

57+
return release_path
58+
3359

3460
def apply_patches_for_release(release: str, repo_path: Path) -> None:
3561
"""Apply patches (if any) for the given release."""
@@ -41,30 +67,24 @@ def apply_patches_for_release(release: str, repo_path: Path) -> None:
4167
def build_docs_for_release(release: str, repo_path: Path, outdir: Path) -> None:
4268
"""Build documentation for a given release."""
4369
print(f"Building docs for {release}")
44-
45-
# Check out release
46-
sp.run(
47-
("git", "-C", str(repo_path), "checkout", release),
48-
check=True,
49-
capture_output=True,
50-
)
70+
release_path = add_worktree_for_release(repo_path, release)
5171

5272
# Apply patches, if any
53-
apply_patches_for_release(release, repo_path)
73+
apply_patches_for_release(release, release_path)
5474

5575
# Build docs
56-
sp.run(("just", f"{repo_path!s}/build-docs"), check=True)
76+
sp.run(("just", f"{release_path!s}/build-docs"), check=True)
5777

5878
# Patch versions.html to redirect to main versions page
59-
with (repo_path / "book" / "versions.html").open("w", encoding="utf-8") as f:
79+
with (release_path / "book" / "versions.html").open("w", encoding="utf-8") as f:
6080
f.write(f"""<head>
6181
<meta http-equiv="Refresh" content="0; URL={DOCS_SITE_ROOT}/versions.html" />
6282
</head>""")
6383

6484
# Move to output directory
6585
release_outdir = outdir / release
6686
print(f"Copying to {release_outdir}")
67-
shutil.move((repo_path / "book"), release_outdir)
87+
shutil.move((release_path / "book"), release_outdir)
6888

6989

7090
def build_old_docs() -> None:
@@ -74,7 +94,7 @@ def build_old_docs() -> None:
7494

7595
# Clone this repo to a temporary directory
7696
with TemporaryDirectory() as tmpdir:
77-
repo_path = Path(tmpdir)
97+
repo_path = Path(tmpdir) / "MUSE2.git"
7898
clone_repo_to(repo_path)
7999

80100
# Generate documentation for each previous release

‎docs/release/__init__.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
import re
44
import subprocess as sp
5+
from pathlib import Path
56

67

78
def is_release_tag(tag: str) -> bool:
@@ -14,8 +15,10 @@ def is_release_tag(tag: str) -> bool:
1415

1516
def get_releases() -> list[str]:
1617
"""Get all release tags for this repo, sorted by semantic version."""
18+
19+
repo_path = Path(__file__).parent
1720
ret = sp.run(
18-
("git", "tag", "-l", "--sort=-version:refname"),
21+
("git", "-C", str(repo_path), "tag", "-l", "--sort=-version:refname"),
1922
capture_output=True,
2023
check=True,
2124
encoding="utf-8",

‎docs/release/patches/v2.0.0/0002-Add-placeholder-other-versions-of-docs-chapter.patch‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
From e0638c6639a5ce322977cafdb4d06b656cd77cb7 Mon Sep 17 00:00:00 2001
2+
From: Alex Dewar <a.dewar@imperial.ac.uk>
3+
Date: Wed, 29 Apr 2026 14:43:12 +0100
4+
Subject: [PATCH] Add placeholder "other versions of docs" chapter
5+
6+
This will redirect to the version in the main version of the docs when built.
7+
---
8+
docs/SUMMARY.md | 1 +
9+
1 file changed, 1 insertion(+)
10+
11+
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
12+
index 5a1d47bf..ab00b928 100644
13+
--- a/docs/SUMMARY.md
14+
+++ b/docs/SUMMARY.md
15+
@@ -15,3 +15,4 @@
16+
- [Model Diagrams](model/model_diagrams.md)
17+
- [Glossary](glossary.md)
18+
- [Developer Guide](developer_guide.md)
19+
+- [Other versions of documentation](versions.md)
20+
--
21+
2.54.0

0 commit comments

Comments
 (0)