Setup and configuration of config docs website

[chrisb13]

As discussed at workshop @chrisb13 @anton-seaice @minghangli-uni @atteggiani @aekiss @dougiesquire

See design/discussion doc here.

[chrisb13]

Related: ACCESS-NRI/ACCESS-Hive-Docs#908

(This was created such that this PR could be started)

[chrisb13]

As this comment, would be good to remove broken links (or ones that have a high potential to break in the future).

[chrisb13]

See discussion here.

In short

We are going to move the all the documentation stubs back into main branch.

I've opened this PR so that we can work towards closing this?

I guess we need to move everything off stubs?

There's also this content: #573

[chrisb13]

@anton-seaice as agreed at last week's TWG. I think it would be helpful to document where we got to last week and the plan going forwards.

Can you please write some notes here on that?

It would also be good to get the ball rolling on what we need for versioning of the docs to be integrated / displayable (this is likely relevant).

[anton-seaice]

From the minutes

We are going to move the all the documentation stubs back into main branch. The current stubs based system have incomplete versioning, are hard to edit and have weird quirks (like links breaking all the time)

Planning to use CalVer versioning for the docs - when doing a config release, a docs release would be manually triggered at that time. (e.g. release-MC_25km_jra_ryf-1.0-beta would align with 2025.08.000 release)

Fixing docs is possible and increments the minor version only (e.g. 2025.08.001 is a future release, still related to release-MC_25km_jra_ryf-1.0-beta but with documentation only corrections)

In future, config and doc releases happen about the same time (e.g. release-MC_25km_jra_ryf-2.0-beta and 2026.0x.xxx docs)

Or my dodgy diagram if preferred:
scan_antons_2025-09-23-16-52-02.pdf

I spent a little time investigating the mike plugin:

1. The most obvious way to do versioning is a plugin called mike. The plugin pushes a built version of the docs, within a folder for the version number, to a gh-pages branch. And then the website would be deployed from a branch on github, rather than the current method through an action. However, its not easy then to make 'pr-previews' - the action would have to commit into the gh-pages branch specifically for that PR and revert it again after merging.

2. If we stay with using deploy with an action - its also messy. We'd have to build every version (i.e. tag) of the docs everytime we deploy the website. This is similar to the current action to deploy PR-previews, but would add a section for tags. And then we can use mike for its version selection. The big risk is that future changes to how the pages are built would break old versions (e.g. if plugins stop working).

3. The easiest option (I think) is to move to hosting on read-the-docs instead of github pages. It handles the versioning in a standardised way and works fine with mkdocs and the material theme etc. https://access-om3-configs.access-hive.org.au/ would have to be redirected to readthedocs instead of github pages (should be trivial).

[dougiesquire]

The easiest option (I think) is to move to hosting on read-the-docs instead of github pages

And we've gone full circle 😆. Is there a need for mike when using readthedocs?

[atteggiani]

It seems to me we are going in circle as well.
I repeat it here if it was not clear during the many meetings and written posts.

The versioning problem is related neither to which framework we use to build the website (mkdocs vs readthedocs) nor to what framework we use to host the website (GitHub pages vs readthedocs) nor to how we build and host it (custom GitHub action vs default gh-pages method).

The versioning problem comes from the actual structure of the versions (multiple independent versions within the same repository and therefore website). In addition to this, the stubs infrastructure makes everything even more complicated.

[anton-seaice]

Thanks Davide - we are going to stop using the stubs , and version the docs with CalVer versions (probably triggered by pushing a git tag). So all the docs will live in the main branch and the website gets built from that. Get Outlook for iOS<https://aka.ms/o0ukef>

…

________________________________ From: Davide Marchegiani ***@***.***> Sent: Friday, October 3, 2025 2:11:59 PM To: ACCESS-NRI/access-om3-configs ***@***.***> Cc: Anton Steketee ***@***.***>; Mention ***@***.***> Subject: Re: [ACCESS-NRI/access-om3-configs] Update config stub management from OSIT ACCESS workshop meeting (Issue #752) [https://avatars.githubusercontent.com/u/30042436?s=20&v=4]atteggiani left a comment (ACCESS-NRI/access-om3-configs#752)<#752 (comment)> It seems to me we are going in circle as well. I repeat it here if it was not clear during the many meetings and written posts. The problem is neither which framework we use to build the website (mkdocs vs readthedocs) nor what framework we use to host the website (GitHub pages vs readthedocs) nor how we build and host it (custom GitHub action vs default gh-pages method). The versioning problem comes from the actual structure of the versions (multiple independent versions within the same repository and therefore website). In addition to this the stubs infrastructure make everything more complicated. — Reply to this email directly, view it on GitHub<#752 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AS4DACCYB4WDH4UTPRVJ2CD3VXZQ7AVCNFSM6AAAAACGGNUIC2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTGNRUGE4DGOBYHA>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[atteggiani]

Thanks Davide - we are going to stop using the stubs , and version the docs with CalVer versions (probably triggered by pushing a git tag). So all the docs will live in the main branch and the website gets built from that.

Oh, when was this decided? I had no idea about it.
How will this look for the different configurations versions?

[anton-seaice]

There will be pages in the main branch to cover individual configurations, or sets of configurations. ( eg there might be a page for each model resolution and it has content related to several configs at that resolution )