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
main branch
- 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
main branch 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.
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
mainbranch on GitHub (which, in theory, should be match the respective code in themainbranch)As we've now started to make releases, we face the likely possibility of different people using different versions of MUSE:
mainbranchThe 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
mainas 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:
mainbranch and one matching the latest 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.