Move dev docs

[AdrianDAlessandro]

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]

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]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.75%. Comparing base (33466f6) to head (5ea6830).

Additional details and impacted files

@@                  Coverage Diff                   @@
##           docs-version-selector    #1366   +/-   ##
======================================================
  Coverage                  89.75%   89.75%           
======================================================
  Files                         58       58           
  Lines                       8529     8529           
  Branches                    8529     8529           
======================================================
  Hits                        7655     7655           
  Misses                       561      561           
  Partials                     313      313           

☔ 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]

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]

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

[alexdewar]

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.

[alexdewar]

If you use a relative link, this will also work locally and means we don't have to hardcode the URL:

Suggested change

	content="0; URL={DOCS_SITE_ROOT}/{get_releases()[0]}/"
	content="0; URL=./{get_releases()[0]}/index.html"

If you do this, you can drop DOCS_SITE_ROOT above.

[alexdewar]

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.