Move dev docs by AdrianDAlessandro · Pull Request #1366 · EnergySystemsModellingLab/MUSE2

AdrianDAlessandro · 2026-06-23T17:03:26Z

Description

This PR moves the development documentation so that is no longer the top-level documentation but is instead alongside the other releases.

There are no longer any top-level docs at all, instead, there is a redirect that takes the user to the most recent (stable) version of the docs when using the link in the readme (https://energysystemsmodellinglab.github.io/MUSE2/).

I have also removed the extra release layer in the url path because it is no longer necessary given the top level docs don't exist at all. So the development docs will now live at https://energysystemsmodellinglab.github.io/MUSE2/dev/ (and replace dev with any version string for other versions)

Fixes #1193
Fixes #1194

Note: Requires #1356 to be merged first

Type of change

Bug fix (non-breaking change to fix an issue)
New feature (non-breaking change to add functionality)
Refactoring (non-breaking, non-functional change to improve maintainability)
Optimization (non-breaking change to speed up the code)
Breaking change (whatever its nature)
Documentation (improve or add documentation)

Key checklist

All tests pass: $ cargo test
The documentation builds and looks OK: $ cargo doc
Update release notes for the latest release if this PR adds a new feature or fixes a bug
present in the previous release

Further checks

Code is commented, particularly in hard-to-understand areas
Tests added that prove fix is effective or that feature works

AdrianDAlessandro · 2026-06-23T17:12:33Z

I am aware that the link checker tests are failing. They will continue to fail until this branch is merged because there are absolute urls that will not exist until after this version of the docs is deployed.

codecov · 2026-06-23T17:13:31Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.60%. Comparing base (3e9d3b5) to head (3df98b5).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1366   +/-   ##
=======================================
  Coverage   89.60%   89.60%           
=======================================
  Files          58       58           
  Lines        8338     8338           
  Branches     8338     8338           
=======================================
  Hits         7471     7471           
  Misses        550      550           
  Partials      317      317

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

dc2917 · 2026-06-24T17:29:58Z

I'm having some trouble getting this to work locally. Quite possibly a me issue but thought I'd check.

Snippets from output of just build-docs all_with_old

Building book
 INFO Book building has started
 INFO Running the html backend
 INFO HTML book written to `/home/dc2917/Documents/MUSE2/book`
Generating API documentation
 Documenting muse2 v2.1.0 (/home/dc2917/Documents/MUSE2)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.47s
   Generated /home/dc2917/Documents/MUSE2/target/doc/muse2/index.html
Moving dev docs to /dev

All seems fine, content is in book directory.

Building docs for v2.1.0
Building book
 INFO Book building has started
 INFO Running the html backend
 INFO HTML book written to `/tmp/tmpa811vp7s/v2.1.0/book`
Generating API documentation
   Compiling muse2 v2.1.0 (/tmp/tmpa811vp7s/v2.1.0)
 Documenting muse2 v2.1.0 (/tmp/tmpa811vp7s/v2.1.0)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.28s
   Generated /tmp/tmpa811vp7s/v2.1.0/target/doc/muse2/index.html
Copying to /home/dc2917/Documents/MUSE2/book/v2.1.0

But I have no book/v.2.1.0 directory

Building docs for v2.0.0
Building book
 INFO Book building has started
 INFO Running the html backend
 INFO HTML book written to `/tmp/tmpa811vp7s/v2.0.0/book`
Generating API documentation
   Compiling highs-sys v1.11.0
   Compiling muse2 v2.0.0 (/tmp/tmpa811vp7s/v2.0.0)
    Checking highs v1.12.0
 Documenting muse2 v2.0.0 (/tmp/tmpa811vp7s/v2.0.0)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 2.62s
   Generated /tmp/tmpa811vp7s/v2.0.0/target/doc/muse2/index.html
Copying to /home/dc2917/Documents/MUSE2/book/v2.0.0

Nor do I have no book/v.2.0.0 directory

I'm therefore getting 404 errors at http://localhost:3000/dev/index.html, http://localhost:3000/v2.1.0/index.html and http://localhost:3000/v2.0.0/index.html

Edit: as discussed in mid-sprint, it's mdbook serve -o that's deleting the book/ directories. Immediately after just build-docs all_with_old I have book/{dev, index.html, v2.0.0, v2.1.0}

alexdewar

I think this is the right approach. A definite improvement!

I've left a few small suggestions and comments.

alexdewar · 2026-06-25T13:34:15Z

Given that we now exclude the docs folder from the link checker, these could all be changed to relative links.

These were kept as absolute links in #1344 because the links might break in future versions of the documentation, so it made sense to keep these link to the version of the docs that these release notes are referring to.

alexdewar · 2026-06-25T13:39:13Z

    var list = document.getElementById("version-list");

-    var versionMatch = /\/release\/(v[\d.]+)\//.exec(path);
+    var versionMatch = /\/(v[\d.]+)\//.exec(path);


This regex doesn't quite make sense to me. I think the [\d.]+ means "a digit or any character (.) repeated at least one times". Could be that JavaScript's syntax is different to what I'm used to.

Honestly, I don't understand regex, and this was co-pilot. I believe it's looking for a version string like "v2.1.0" so I interpreted the \d to mean an integer and the . to mean a decimal point. It does work like that, so I was inclined to trust it.

alexdewar · 2026-06-25T14:19:29Z

PS -- I realised there are some other places in the repo (e.g. under src/) where we have absolute links to the docs that will need changing. If the URL is just pointing at the root, i.e. https://energysystemsmodellinglab.github.io/MUSE2/, it'll be fine, but e.g. https://energysystemsmodellinglab.github.io/MUSE2/file_formats/ would need changing to https://energysystemsmodellinglab.github.io/MUSE2/dev/file_formats/.

Obvs if anyone has any of the old pages bookmarked, those old URLs won't work anymore, which I think is fine.

AdrianDAlessandro · 2026-07-01T13:36:08Z

I'm looking into addressing some of these comments... But I've found an annoying issue with the 404 pages not rendering properly in deployment. For example https://energysystemsmodellinglab.github.io/MUSE2/bad.html

@alexdewar

Co-authored-by: @alexdewar

Copilot

Pull request overview

This PR reorganises the documentation output layout so the current (development) docs live at /dev/ alongside versioned release docs at /vX.Y.Z/, and updates in-repo references accordingly. It also adds a root index.html redirect to send users to the most recent stable docs.

Changes:

Update CLI help text + tests to point to /v{CARGO_PKG_VERSION}/ instead of /release/v{…}/.
Update the docs version widget to detect /vX.Y.Z/ paths and treat everything else as dev.
Add a script + Just recipes to move the built dev docs under book/dev/ and generate old-version docs as siblings in book/.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/cli.rs	Updates help output assertion for the new versioned docs URL layout.
src/cli.rs	Updates CLI `after_help` docs URL to match the new layout.
docs/templates/header.hbs.jinja	Adjusts version detection + labels for the new `/dev/` + `/vX.Y.Z/` structure.
docs/release_notes/v2.1.0.md	Updates absolute release-note links to match the new docs paths.
docs/move_dev_docs.py	New script intended to move `book/` into `book/dev/` and create a stable redirect.
docs/build_old_docs.py	Writes old-version docs directly into `book/vX.Y.Z/` instead of `book/release/vX.Y.Z/`.
build-docs.just	Adds `move-dev` step and rewires `old` docs build to use it.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

AdrianDAlessandro · 2026-07-01T18:07:04Z

+    bookdir = REPO_ROOT / "book"
+    outdir = REPO_ROOT / "book" / "dev"
+
+    with TemporaryDirectory() as tmpdir:
+        # Move book to temporary directory
+        shutil.move(bookdir, tmpdir)
+        shutil.move(Path(tmpdir) / "book", outdir)
+


This sounds correct... but the code works as is, so I'm not inclined to change it

AdrianDAlessandro · 2026-07-01T18:07:57Z

+    # Redirect to stable (most recent) version of docs
+    with (bookdir / "index.html").open("w", encoding="utf-8") as f:
+        f.write(f"""<head>
+    <meta
+        http-equiv="Refresh"
+        content="0; URL=./{get_releases()[0]}/index.html"
+    />
+</head>""")


This is an edge-case that I don't think we need to worry about

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

AdrianDAlessandro · 2026-07-01T18:10:54Z

PS -- I realised there are some other places in the repo (e.g. under src/) where we have absolute links to the docs that will need changing. If the URL is just pointing at the root, i.e. https://energysystemsmodellinglab.github.io/MUSE2/, it'll be fine, but e.g. https://energysystemsmodellinglab.github.io/MUSE2/file_formats/ would need changing to https://energysystemsmodellinglab.github.io/MUSE2/dev/file_formats/.

Obvs if anyone has any of the old pages bookmarked, those old URLs won't work anymore, which I think is fine.

I've addressed this, but instead of linking to the dev version, it will now link to the corresponding version of the docs.

AdrianDAlessandro requested review from alexdewar, dc2917 and tsmbland June 23, 2026 17:03

Base automatically changed from docs-version-selector to main June 24, 2026 17:00

This was linked to issues Jun 24, 2026

Reorganise docs output folder so that main version of docs is in the same place as other versions #1193

Open

Make last release's docs the one that users land on #1194

Open

alexdewar mentioned this pull request Jun 25, 2026

mdbook serve clobbers old versions of docs #1367

Open

alexdewar requested changes Jun 25, 2026

View reviewed changes

alexdewar mentioned this pull request Jun 25, 2026

Add documentation for commodity price calculations #1362

Merged

11 tasks

Copilot AI review requested due to automatic review settings July 1, 2026 14:54

Copilot started reviewing on behalf of AdrianDAlessandro July 1, 2026 14:54 View session

AdrianDAlessandro added 5 commits July 1, 2026 15:55

Move development version of docs into release/dev

a582187

Redirect to stable version of docs from URL root. Close #1194

8bb740b

Remove unnecesary release/ layer in docs path

3e8374b

Fix failing cli test (wrong url in test)

f1b6408

Use a relative path for the redirect url in the index.

6776de3

Co-authored-by: @alexdewar

AdrianDAlessandro force-pushed the move-dev-docs branch from 4311bff to 6776de3 Compare July 1, 2026 14:55

Copilot AI reviewed Jul 1, 2026

View reviewed changes

AdrianDAlessandro and others added 5 commits July 1, 2026 17:17

Link to latest version of docs in api documentation text.

1f4419e

Fix link not rendering properly and make relative

c2e5b63

Use homepage instead of documentation in Cargo.toml to get env var

918339a

Use docs_url! macro for linking to docs throughout docstrings

8e7337b

Fix docstring and require api for move_docs

3df98b5

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Uh oh!

Conversation

AdrianDAlessandro commented Jun 23, 2026

Description

Type of change

Key checklist

Further checks

Uh oh!

AdrianDAlessandro commented Jun 23, 2026

Uh oh!

codecov Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

dc2917 commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexdewar left a comment

Choose a reason for hiding this comment

Uh oh!

alexdewar Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

AdrianDAlessandro Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

alexdewar Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

AdrianDAlessandro Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alexdewar commented Jun 25, 2026

Uh oh!

AdrianDAlessandro commented Jul 1, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

AdrianDAlessandro Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AdrianDAlessandro Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AdrianDAlessandro commented Jul 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov Bot commented Jun 23, 2026 •

edited

Loading

dc2917 commented Jun 24, 2026 •

edited

Loading