User documentation for ACCESS OM3 025 release.

[chrisb13]

Following this chat, this issue is to begin the process of discussing/creating user documentation for the upcoming ACCESS OM3 025 release.

Also recently discussed here; more general discussion/useful criteria here. Background:

• Importance of having configuration-specific documentation that is easily updatable and citable.
• @anton-seaice: consider using the wiki on GitHub for documentation. Drawbacks: not citable or packageable.
• Potential use of tools like Sphinx for generating documentation.
• @dougiesquire: consider doc’s partially living within each of the configuration branches. Citable doc’s are better and mean they can be updated as configurations are updated. Sphinx docs are likely more citable than a wiki? (Meeting suggestion sounded like a Zenodo achieve likely didn’t include the wiki)

Opening suggestion then... We create a Sphinx config doc that has a general section and then stubs in the specific branches where required (like option 2 here). If useful, could be programmatically generated such that new changes are picked up when changes are made.

What about the wiki' contents? If we want to have docs that are citable I think they should be moved to a sphinx doc as well? Should that live in the build repo'?

@dougiesquire, you've been talking about some Wombat Sphinx doc's, is this compatible with your plan? (ping @pearseb)

Happy for further feedback: @aekiss @AndyHoggANU @aidanheerdegen @atteggiani.

[anton-seaice]

Opening suggestion then... We create a Sphinx config doc that has a general section and then stubs in the specific branches where required (like option 2 here). If useful, could be programmatically generated such that new changes are picked up when changes are made.

This suggestion is good but my feeling is it's overly complicated, and we should just have a central set of docs which have tables / notes in places where different configurations diverge. And maybe have seperate stubb / short docs for different configurations as a future goal.

The downside in my view is that it means the docs always need reviewing for all changes - which is good for quality but burdensome.

What about the wiki' contents? If we want to have docs that are citable I think they should be moved to a sphinx doc as well? Should that live in the build repo'?

Yes i think the wiki is the beginnings of these docs. I think it should live in the configurations repo (which is the repo most users will look at and mostly docs are about configuration choices, rather than model option/implementation).

[chrisb13]

This suggestion is good but my feeling is it's overly complicated, and we should just have a central set of docs which have tables / notes in places where different configurations diverge. And maybe have seperate stubb / short docs for different configurations as a future goal.

Okay, sounds great. So to be explicit, we are thinking of a Sphinx doc here:
https://github.com/aCCESS-NRI/acceSS-OM3-configs
In the main branch?

Where a starting point is..

Yes i think the wiki is the beginnings of these docs. I think it should live in the configurations repo (which is the repo most users will look at and mostly docs are about configuration choices, rather than model option/implementation).

The downside in my view is that it means the docs always need reviewing for all changes - which is good for quality but burdensome.

Yeah, I think we can make it more complex as the need arises. I'm hoping that some of the differences can be programmatically generated.

[anton-seaice]

Okay, sounds great. So to be explicit, we are thinking of a Sphinx doc here:
https://github.com/aCCESS-NRI/acceSS-OM3-configs
In the main branch?

Good by me - others will have other views !

[dougiesquire]

I think that's a good starting point. We can integrate config-specific docs if/when the need arises. At the very least, including in the docs an up-to-date set of parameters for each config should be pretty straightforward.

[chrisb13]

Thanks @anton-seaice @dougiesquire.

Had a chat to @atteggiani and @aidanheerdegen about this today. We pro/con'd Sphinx vs Mkdoc (the latter is currently used for the access hive docs). I'm leaning slightly towards mkdoc, simply because organisationally, we have expertise and infrastructure already in using mkdoc, namely, some CI infrastructure to support it (e.g. CI builds on PRs). I'm aware that some of the team (@dougiesquire?, myself) have experience/familiarity with Sphinx. On the other hand, as we already use mkdoc, I think being able to transfer doc text / links etc between the two kinds of docs seems a strong advantage to me.

@aidanheerdegen made the point that Mkdoc is native markdown, which we use everywhere already. It seems this is possible with Sphinx too (less conventional perhaps?)

Anyone see any issues with this approach? (proceeding with mkdoc rather than sphinx)

[dougiesquire]

I'm leaning slightly towards mkdoc, simply because organisationally, we have expertise and infrastructure already in using mkdoc, namely, some CI infrastructure to support it (e.g. CI builds on PRs)

Note, there are also quite a few ACCESS-NRI projects using Sphinx. These also include automated docs builds on PRs.

I don't have a strong opinion re mkdocs vs Sphinx for ACCESS-OM3 documentation. When I last looked at this a while back, I think I convinced myself that Sphinx was more flexible and had many more useful extensions. However, many of the extensions I use are to auto-generate documentation from code which isn't really relevant in this case.

I've used the myst_parser extension in the past to use markdown in Sphinx docs. I don't think I've ever had a Sphinx project that is entirely markdown, but I also don't find rst that onerous.

[atteggiani]

I have never used Sphinx so I don't know what are the advantages of it compared to Mkdocs.

However, there are many plugins for Mkdocs as well (for example auto-generation of code from docstrings is still possible with mkdocstrings, and many more plugins are available).
So, if the main reason to go with Sphinx is its flexibility, I don't think that apply as much anymore nowadays.

I think in general, being able to use markdown is a big advantage because it makes the documentation much easier to be developed by most of us and highly reduces the learning curve for it. So, in any case, I think markdown should be prioritised (when possible) as a format for documentation.

[chrisb13]

Thanks @atteggiani and @dougiesquire for sharing your experiences. Sounds like there isn't a strong preference and we can proceed with mkdoc.

In general and if practical, I think it would be good to have a consistent approach across om3 -- makes moving parts of the docs around trivial. @dougiesquire, I know you're about to make some wombat doc's, would you be able to use mkdoc there too?

@aekiss @minghangli-uni @ezhilsabareesh8 @anton-seaice any objections?

[dougiesquire]

@dougiesquire, I know you're about to make some wombat doc's, would you be able to use mkdoc there too?

Yup sure

[chrisb13]

Ok, great.

I'll be in touch, might make sense to do the wombat ones at the same time then?

[access-hive-bot]

This issue has been mentioned on ACCESS Hive Community Forum. There might be relevant details there:

https://forum.access-hive.org.au/t/cosima-twg-meeting-minutes-2025/4067/7

[chrisb13]

Current version is here. See related discussion.