Documentation page for each release #1072
Description
We currently have a single version of the documentation online here https://energysystemsmodellinglab.github.io/MUSE2/ which matches the latest version of the documentation on the main branch on GitHub (which, in theory, should be match the respective code in the main branch)
As we've now started to make releases, we face the likely possibility of different people using different versions of MUSE:
- Us developers using the
mainbranch - Users using the latest release
- Users using an old release (or had used an old release in the past and wants to retrospectively look at the documentation for that version)
The problem here is that as we make changes to the code, especially user facing code, a single documentation site cannot possibly be accurate for all versions of MUSE that people might be using, which might cause considerable confusion. We want to update the documentation on main as we make changes to the code, but doing so might make the online documentation site inaccurate for people using a release.
A few possible solutions from easiest to hardest:
- Have the documentation site match the latest release. This would keep a single documentation version online, but one that's accurate for most users (we'd encourage most users to be using the latest version anyway). It would no longer be accurate for us developers, but that's not such a problem as we can build it locally anyway
- Have a "dev" version and a "release" version of the documentation online. One matching the
mainbranch and one matching the latest release. - Have a documentation version for each release
I imagine all of these would involve some challenges. It was easy to do the third option with MUSE1 using readthedocs, but mdbook is a different beast and it seems not so straightforward.