Update Run CM2 docs

[paigem]

ACCESS-Hive Docs

Description

This PR is meant as a test for trying out some ideas of how we could update the Run ACCESS-CM2 (and potentially similar) pages. So for now this is just a draft PR.

First, I am testing how the documentation looks with expandable sections. Later I may try a few other things, and will add a comment to indicate what I test.

[github-actions]

PR Preview
🚀 Preview of PR head commit a7eef5a deployed to https://docs.access-hive.org.au/pr-previews/1172
2026-07-03 16:47 AEST
Preview generated through the Deploy to GitHub Pages workflow run 28643610391.

[ccarouge]

@paigem following my question on Zulip about the redesign of ACCESS-Hive docs, @heidinett has shown me this PR. I have a few comments after working on the Rose/Cylc and Payu pages.

1. I would have a blurb at the start to say that ACCESS-CM2 uses the Rose/Cylc workflow manager to manage configurations and experiments
2. I would start with the Prerequisites and then a "Rose/Cylc" section that encompasses the current ARE, persistent sessions and setup. Then it is followed by the specific CM2 sections.
3. Under the "Rose/Cylc" section, I would have a "terminology and file organisation" section. We have that in the Payu page, and I think it works well at presenting the vocabulary and the organisation of files for the workflow manager. I would put the explanation of the location of outputs and restarts (this part) in there, as well as the explanation of the suites and suite-id. I found also the "Where the suite is copied to" box that would be good in a file organisation section. There might be more stuff, I haven't read the whole page. Putting all these definitions at the top, makes it easier for more experienced users to skip. And they are specific to the workflow manager but not the model. Some details might be model specific but we can tease these out.
4. More minor at this stage, I wonder if the box under Edit ACCESS-CM2 suite configuration is too monolithic and will be easier to use if split. But it's probably something that needs more thought than I put into this.

[ccarouge]

@paigem @heidinett Reading the docs, I think we could use the Snippets sections feature. This way, we could have the payu instructions, for example, in a single file, and use snippet sections to add the information bits by bits to the Run a Model pages. This would prevent a proliferation of include files, hence, solving the filenaming issue, make it easier to find the information for payu for developers of the documentation and making sure the information between several snippets is coherent.

I'm pretty sure I saw the same functionality with Macros. Macros and Snippets seem pretty interchangeable for include files. I think I'd rather keep the Macros usage to real macro/templating cases, but there is no real justification to this choice.

[atteggiani]

I'm pretty sure I saw the same functionality with Macros. Macros and Snippets seem pretty interchangeable for include files. I think I'd rather keep the Macros usage to real macro/templating cases, but there is no real justification to this choice.

I agree.
However, there might be uses for templating especially when including the same content in multiple different parts but needing to modify it with specific parts such as model names, branches, etc.

Therefore, I think macros works better in most cases.

This way, we could have the payu instructions, for example, in a single file, and use snippet sections to add the information bits by bits to the Run a Model pages.

I think the only feature that snippets allows and macros doesn't is the possibility to reference a particular "section" of an included file.

However, I am not in favor of this choice for some reasons:

1. If we choose to start using snippets/macros to include the same content in multiple pages (which I think is a good approach), there is no need for a "Payu" or "Cylc" page anymore, because each portion of the contents relating to payu/cylc would be easily included from the same source by using snippets/macros.
2. Having multiple include files, grouped in subfolders per topic for example, would keep each include portion relatively short and easy to maintain. Whereas a long file that is never used as a whole (because we would always be using separate sections from it) would be harder to maintain.

[ccarouge]

@atteggiani

Having multiple include files, grouped in subfolders per topic for example, would keep each include portion relatively short and easy to maintain. Whereas a long file that is never used as a whole (because we would always be using separate sections from it) would be harder to maintain.

It's interesting because I think totally the opposite in terms of ease of maintenance. To me, it seems keeping information coherent across related but separate files would be harder than when the bits and pieces are together in the same file. And I like the non-proliferation of files... But I have no experience either way, so this opinion is only based on a feeling.

[atteggiani]

It's interesting because I think totally the opposite in terms of ease of maintenance. To me, it seems keeping information coherent across related but separate files would be harder than when the bits and pieces are together in the same file. And I like the non-proliferation of files... But I have no experience either way, so this opinion is only based on a feeling.

Your point about coherence makes sense.
I don't know what's the better approach as I also base my opinion on a feeling.
In any case, if the single-file for inclusions only has paragraphs related to the same topic (e.g., Payu), there shouldn't be issues about having one single file instead of multiple ones.

For the framework to use, I would still vouch for using macros in all cases.
It has very good built-in functions and it can also be easily extended by creating custom macros if needed (see the mkdocs-macros getting started example).

In our case, for example, if we want to allow the inclusion of only subsections (e.g. only some specific lines) of an include file, we can create a custom macro in the main.py similar to:

import os
def define_env(env):

    @env.macro
    def include_lines(path, start_line=None, end_line=None):
        include_dir = env.config.get('include_dir') or env.conf['docs_dir']
        full_path = os.path.join(include_dir, path)
        with open(full_path, 'r') as f:
            lines = f.readlines()
        start = (start_line - 1) if start_line else None
        end = end_line if end_line else None
        content = ''.join(lines[start:end])
        return env.render(sliced)

And then use it as

{{ include_lines("path/to/file", <start>, <end> }}

This is only a quick example I made with AI, but we could extend this by being able to select paragraphs instead of lines, or we could do almost anything we'd like.