Creating a skeleton structure for ESM1.6 configuration docs #237

chrisb13 · 2025-10-21T02:52:20Z

Following up regarding having an ESM1.6 docs meeting. This is to set a basic structure as a staring point for the ESM1.6 config docs for a meeting with @chrisb13, @ccarouge, @paigem and @rml599gh (Rachel Law).

Note that there are two main sets of docs:

I've created a starting point for both.

Additionally @anton-seaice et al. has started some notes for sea ice
#234

If you're interested to see what we've been doing for OM3, it's here:
https://access-om3-configs.access-hive.org.au/

We also have this document:
https://anu365.sharepoint.com/:w:/r/sites/ACCESS-NRI/_layouts/15/Doc.aspx?sourcedoc=%7BBAE387EE-8E88-46DF-B869-001DC246F14F%7D&file=ESM1.6%20config%20doc%20initial%20reflections.docx&fromShare=true&action=default&mobileredirect=true

And these two discussions:

FYI @ccarouge @paigem @anton-seaice and @Whyborn (who was interested in a starting "template")

github-actions · 2025-10-21T02:52:53Z

PR Preview
⚠️ There was an error in the pr-preview deployment.
For more information check the Actions tab.
2025-10-21 13:52 AEDT

chrisb13 · 2025-10-21T23:33:25Z

Any idea why this PR-preview isn't working @atteggiani ?

I have a feeling it's related to the plug-in that @anton-seaice is using?

  Switched to a new branch '214-main'
  branch '214-main' set up to track 'origin/214-main'.
  SITE_URL=https://access-nri.github.io/access-esm1.6-configs/pr-preview-234 mkdocs build -f mkdocs.yml -d /home/runner/work/access-esm1.6-configs/access-esm1.6-configs/website/pr-preview-234
  INFO    -  [include_stubs] 'git' version: git version 2.51.0
  INFO    -  [include_stubs] 'gh' version: gh version 2.80.0 (2025-09-23)
  https://github.com/cli/cli/releases/tag/v2.80.0
  INFO    -  [include-stubs] '-f' or '--config-file' option passed.
  INFO    -  [include-stubs] Running the command 'mkdocs build -f mkdocs.yml -d /home/runner/work/access-esm1.6-configs/access-esm1.6-configs/website/pr-preview-234' using the default mkdocs executable.
  ERROR   -  Config value 'plugins': The "mkdocs-jupyter" plugin is not installed

chrisb13 · 2025-10-21T23:55:19Z

Thanks to @rml599gh @ccarouge @paigem for having a chat yesterday, here's the notes from our meeting.
ESM1.6 config doc initial reflections.docx

We agreed that I should go ahead and create the template we fleshed out (including a few of @anton-seaice's comments).

@ccarouge will review. Then we'll merge and create a mega-issue where people can be assigned sections, with separate issues for each assigned task. (Rather like what was done here)

atteggiani · 2025-10-21T23:59:58Z

Any idea why this PR-preview isn't working @atteggiani ?

I have a feeling it's related to the plug-in that @anton-seaice is using?

  Switched to a new branch '214-main'
  branch '214-main' set up to track 'origin/214-main'.
  SITE_URL=https://access-nri.github.io/access-esm1.6-configs/pr-preview-234 mkdocs build -f mkdocs.yml -d /home/runner/work/access-esm1.6-configs/access-esm1.6-configs/website/pr-preview-234
  INFO    -  [include_stubs] 'git' version: git version 2.51.0
  INFO    -  [include_stubs] 'gh' version: gh version 2.80.0 (2025-09-23)
  https://github.com/cli/cli/releases/tag/v2.80.0
  INFO    -  [include-stubs] '-f' or '--config-file' option passed.
  INFO    -  [include-stubs] Running the command 'mkdocs build -f mkdocs.yml -d /home/runner/work/access-esm1.6-configs/access-esm1.6-configs/website/pr-preview-234' using the default mkdocs executable.
  ERROR   -  Config value 'plugins': The "mkdocs-jupyter" plugin is not installed

Yes, the root issue is that the current Deploy to GitHub Pages worfklow is outdated, it uses the same configurations from the triggering commit, which is not good.
In general I would suggest replacing it with the newer version (will also need to add this workflow for message deletion).

…ccarouge

…ccarouge (#237 (comment)) and updating GitHub pages workflow as per @attenggiani suggestion (#237 (comment)) since pr-preview is not currently working

github-actions · 2025-10-22T00:08:55Z

PR Preview
🛫 The preview of PR head commit 60328f87cef3697f132c0e2ffe8140d077f5c20a is currently being deployed. The preview URL will be available once the deployment completes. For further details, please check the Actions tab.
2025-10-22 11:08 AEDT

github-actions · 2025-10-22T00:09:29Z

PR Preview
⚠️ There was an error in the pr-preview deployment.
For more information check the Actions tab.
2025-10-22 11:08 AEDT

chrisb13 · 2025-10-22T00:11:38Z

@atteggiani I think I did what you suggested (updated the two files --> 60328f8) but it still didn't work. Seems to fail on quite a few errors now:
https://github.com/ACCESS-NRI/access-esm1.6-configs/actions/runs/18701170526/job/53330105635

Feel free to just commit to this branch if you know how to fix it...

github-actions · 2025-10-22T00:18:14Z

PR Preview
🛫 The preview of PR head commit 3232fe02073d7d180ee95cd55ff87582a5f5eb4f is currently being deployed. The preview URL will be available once the deployment completes. For further details, please check the Actions tab.
2025-10-22 11:17 AEDT

github-actions · 2025-10-22T00:18:58Z

PR Preview
⚠️ There was an error in the pr-preview deployment.
For more information check the Actions tab.
2025-10-22 11:17 AEDT

…gs/edit/main/README.md, I would suggest we remove most of it and just re-direct to this page

github-actions · 2025-10-22T00:24:56Z

PR Preview
🛫 The preview of PR head commit a24b1a856cb437196ad90a626bc9513e016c9530 is currently being deployed. The preview URL will be available once the deployment completes. For further details, please check the Actions tab.
2025-10-22 11:24 AEDT

github-actions · 2025-10-22T00:25:37Z

PR Preview
⚠️ There was an error in the pr-preview deployment.
For more information check the Actions tab.
2025-10-22 11:24 AEDT

github-actions · 2025-10-22T00:33:00Z

PR Preview
🛫 The preview of PR head commit 19c1f2148e366e5bb78b6ceda96b1dd85ddfdb29 is currently being deployed. The preview URL will be available once the deployment completes. For further details, please check the Actions tab.
2025-10-22 11:32 AEDT

github-actions · 2025-10-22T00:33:50Z

PR Preview
⚠️ There was an error in the pr-preview deployment.
For more information check the Actions tab.
2025-10-22 11:32 AEDT

atteggiani · 2025-10-22T00:36:34Z

@atteggiani I think I did what you suggested (updated the two files --> 60328f8) but it still didn't work. Seems to fail on quite a few errors now: https://github.com/ACCESS-NRI/access-esm1.6-configs/actions/runs/18701170526/job/53330105635

Feel free to just commit to this branch if you know how to fix it...

It should be replaced in main (not in a PR), and it should be slightly modified.

I can open a PR for it later today.

chrisb13 · 2025-10-22T00:40:38Z

@atteggiani I think I did what you suggested (updated the two files --> 60328f8) but it still didn't work. Seems to fail on quite a few errors now: https://github.com/ACCESS-NRI/access-esm1.6-configs/actions/runs/18701170526/job/53330105635
Feel free to just commit to this branch if you know how to fix it...

It should be replaced in main (not in a PR), and it should be slightly modified.

I can open a PR for it later today.

Oh okay, well I guess we could merge this if you prefer for it to go to main that way?

(I don't mind).

I just tested this locally and it builds okay so I think it's just the github stuff. Please ping me and @ccarouge when it's working :)

ccarouge

I have some more changes to make but they require I set this up locally so I'm just recording these comments for now.

documentation/docs/pages/index.md

documentation/docs/pages/contributing/index.md

documentation/docs/pages/index.md

ccarouge · 2025-10-22T05:30:16Z

@atteggiani @anton-seaice I'm trying to work on these config docs locally but I get an error in mkdocs serve. Any idea about the source of the error is welcome:

$brew install --cask miniforge

$python --version
Python 3.12.11

$cd access-esm1.6-configs/

$cd documentation/

$pip install -r requirements.txt
[Install output ...]
Successfully installed GitPython-3.1.45 MarkupSafe-3.0.3 babel-2.17.0 backrefs-5.9 beautifulsoup4-4.14.2 click-8.3.0 ghp-import-2.1.0 gitdb-4.0.12 jinja2-3.1.6 latexcodec-3.0.1 markdown-3.9 mergedeep-1.3.4 mkdocs-1.6.1 mkdocs-bibtex-4.4.0 mkdocs-events-plugin-0.1 mkdocs-get-deps-0.2.0 mkdocs-git-revision-date-localized-plugin-1.2.0 mkdocs-include-stubs-plugin-1.0.2 mkdocs-macros-plugin-1.0.4 mkdocs-material-9.6.11 mkdocs-material-extensions-1.3.1 paginate-0.5.7 pathspec-0.12.1 pybtex-0.25.1 pygments-2.19.2 pymdown-extensions-10.16.1 pypandoc-1.15 pypandoc_binary-1.15 python-dateutil-2.9.0.post0 pytz-2025.2 pyyaml-6.0.3 pyyaml-env-tag-1.1 responses-0.25.8 six-1.17.0 smmap-5.0.2 soupsieve-2.8 termcolor-3.1.0 typing-extensions-4.15.0 validators-0.35.0 versioneer-0.29 watchdog-6.0.0

$mkdocs serve
INFO    -  [include_stubs] 'git' version: git version 2.39.5 (Apple Git-154)
Traceback (most recent call last):
  File "/opt/homebrew/Caskroom/miniforge/base/bin/mkdocs", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/opt/homebrew/Caskroom/miniforge/base/lib/python3.12/site-packages/include_stubs/cli.py", line 204, in main
    print_exe_version(exe)
  File "/opt/homebrew/Caskroom/miniforge/base/lib/python3.12/site-packages/include_stubs/utils.py", line 104, in print_exe_version
    version = run_command([executable, "--version"])
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/Caskroom/miniforge/base/lib/python3.12/site-packages/include_stubs/utils.py", line 82, in run_command
    result = _run_command(command)
             ^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/Caskroom/miniforge/base/lib/python3.12/subprocess.py", line 548, in run
    with Popen(*popenargs, **kwargs) as process:
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/Caskroom/miniforge/base/lib/python3.12/subprocess.py", line 1026, in __init__
    self._execute_child(args, executable, preexec_fn, close_fds,
  File "/opt/homebrew/Caskroom/miniforge/base/lib/python3.12/subprocess.py", line 1955, in _execute_child
    raise child_exception_type(errno_num, err_msg, err_filename)
FileNotFoundError: [Errno 2] No such file or directory: 'gh'

anton-seaice · 2025-10-22T05:41:46Z

I had that too, I don't remember what I did. Maybe i just installed gh ?

Its a strange error, because the stubs are not included in mkdocs.yml (although the plugin is still in the requirements.txt file). Alternatively, try uninistalling mkdocs_include_configuration_stubs_plugin

atteggiani · 2025-10-22T05:56:21Z

@ccarouge
The mkdocs_include_configuration_stubs_plugin needs gh to be installed on the system.
Either install gh, or if the plugin is not being used anymore, simply uninstall it (you will have to reinstall mkdocs afterwards though).

chrisb13 · 2025-10-22T06:36:37Z

I have some more changes to make but they require I set this up locally so I'm just recording these comments for now.

Thanks @ccarouge

I think I'd prefer to wait till @atteggiani can fix the pr-preview before rolling through these changes.

(For this kind of first hack, in future, I'd be happy for you to just commit the changes by the way.)

github-actions · 2025-10-22T08:09:50Z

PR Preview
🚀 Preview of PR head commit `a887956` deployed to https://access-nri.github.io/access-esm1.6-configs/pr-previews/237
2025-10-24 11:57 AEDT
Preview generated through the Deploy to GitHub Pages workflow run 18766254508.

Co-authored-by: Claire Carouge <[email protected]>

chrisb13 · 2025-10-23T05:24:01Z

@ccarouge the PR preview is now working. Thanks @atteggiani!

Did you want to have another glance? I've applied your straightforward suggestions (with one edit)

ccarouge · 2025-10-23T22:22:29Z

@ccarouge The mkdocs_include_configuration_stubs_plugin needs gh to be installed on the system. Either install gh, or if the plugin is not being used anymore, simply uninstall it (you will have to reinstall mkdocs afterwards though).

Shouldn't gh be listed in the requirements then?

ccarouge · 2025-10-23T22:28:31Z

@chrisb13

(For this kind of first hack, in future, I'd be happy for you to just commit the changes by the way.)

Except for doing a review/giving feedback, I much prefer to go through the review panel provided by GitHub that doesn't allow me to commit directly. I think it allows me to make suggestions and maybe to apply them afterwards but since I hadn't finished with my feedback in this case, I didn't see the need.

atteggiani · 2025-10-23T22:30:11Z

@ccarouge The mkdocs_include_configuration_stubs_plugin needs gh to be installed on the system. Either install gh, or if the plugin is not being used anymore, simply uninstall it (you will have to reinstall mkdocs afterwards though).

Shouldn't gh be listed in the requirements then?

It's listed in mkdocs_include_configuration_stubs_plugin's requirements. There's no way to specify it in the requirements.txt because it cannot be installed through pip.
In any case, this plugin is not needed anymore, so it can be deleted from the requirements and mkdocs.yaml (it's already deleted in main).

chrisb13 · 2025-10-23T22:35:23Z

since I hadn't finished with my feedback in this case, I didn't see the need.

Oh so you're still doing your review?

My broader point is that we've already heavily discussed this so I think just make the changes you see fit and merge. It's just a starting point for others to add content.

- Removed duplicated pages - added more model component pages - fixed heading levels for TOC

ccarouge · 2025-10-24T00:02:31Z

@chrisb13 (and anyone interested), I've finished with my feedback. I've realised the Word doc had duplication (both alternate structures for Inputs were written). So I've removed the duplicated stuff and some smaller updates around the TOC and model components.

I still think tabs would be nice but we don't have to decide now.

chrisb13 · 2025-10-24T00:57:10Z

@ccarouge thanks for the revisions. I think I've now addressed all your comments. Please feel free to approve and squash-merge.

chrisb13 · 2025-10-24T06:18:45Z

Thanks for your help @ccarouge @rml599gh @anton-seaice !

access-hive-bot · 2025-10-24T06:27:05Z

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

https://forum.access-hive.org.au/t/access-esm1-6-development/3114/269

Fix edit URI in mkdocs configuration

f7821dd

chrisb13 changed the title ~~Fix edit URI in mkdocs configuration~~ Creating a skeleton structure for ESM1.6 configuration docs Oct 21, 2025

adding toc and starting point structure as agreed with @rml599gh and @…

60328f8

…ccarouge (#237 (comment)) and updating GitHub pages workflow as per @attenggiani suggestion (#237 (comment)) since pr-preview is not currently working

adding the discussed section headings

3232fe0

adding content from https://github.com/ACCESS-NRI/access-esm1.6-confi…

a24b1a8

…gs/edit/main/README.md, I would suggest we remove most of it and just re-direct to this page

few updates to make it more relevant to esm1.6

19c1f21

chrisb13 mentioned this pull request Oct 22, 2025

Remove melt diagnostic #242

Open

ccarouge requested changes Oct 22, 2025

View reviewed changes

chrisb13 mentioned this pull request Oct 22, 2025

Update deployment workflow #243

Merged

2 tasks

Merge branch 'main' into 217-configdoc_restructure

0c490c2

Apply suggestions from code review

dc068de

Co-authored-by: Claire Carouge <[email protected]>

ccarouge added 2 commits October 24, 2025 10:45

Additional edits to structure

e3e8e07

- Removed duplicated pages - added more model component pages - fixed heading levels for TOC

A bit more details from the word doc

e616c18

chrisb13 added 2 commits October 24, 2025 11:47

addressing @ccarouge's comments from the review

979465f

addressing another one of claire's comments

a887956

ccarouge approved these changes Oct 24, 2025

View reviewed changes

ccarouge merged commit fecf812 into main Oct 24, 2025
15 checks passed

chrisb13 deleted the 217-configdoc_restructure branch October 24, 2025 06:17

chrisb13 mentioned this pull request Oct 24, 2025

Docs on Sea Ice Diagnostics #234

Open

Creating a skeleton structure for ESM1.6 configuration docs #237

Creating a skeleton structure for ESM1.6 configuration docs #237

Uh oh!

Conversation

chrisb13 commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chrisb13 commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chrisb13 commented Oct 21, 2025

Uh oh!

atteggiani commented Oct 21, 2025

Uh oh!

github-actions bot commented Oct 22, 2025

Uh oh!

github-actions bot commented Oct 22, 2025

Uh oh!

chrisb13 commented Oct 22, 2025

Uh oh!

github-actions bot commented Oct 22, 2025

Uh oh!

github-actions bot commented Oct 22, 2025

Uh oh!

github-actions bot commented Oct 22, 2025

Uh oh!

github-actions bot commented Oct 22, 2025

Uh oh!

github-actions bot commented Oct 22, 2025

Uh oh!

github-actions bot commented Oct 22, 2025

Uh oh!

atteggiani commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chrisb13 commented Oct 22, 2025

Uh oh!

ccarouge left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ccarouge commented Oct 22, 2025

Uh oh!

anton-seaice commented Oct 22, 2025

Uh oh!

atteggiani commented Oct 22, 2025

Uh oh!

chrisb13 commented Oct 22, 2025

Uh oh!

github-actions bot commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chrisb13 commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ccarouge commented Oct 23, 2025

Uh oh!

ccarouge commented Oct 23, 2025

Uh oh!

atteggiani commented Oct 23, 2025

Uh oh!

chrisb13 commented Oct 23, 2025

Uh oh!

ccarouge commented Oct 24, 2025

Uh oh!

chrisb13 commented Oct 24, 2025

Uh oh!

Uh oh!

chrisb13 commented Oct 21, 2025 •

edited

Loading

github-actions bot commented Oct 21, 2025 •

edited

Loading

chrisb13 commented Oct 21, 2025 •

edited

Loading

atteggiani commented Oct 22, 2025 •

edited

Loading

github-actions bot commented Oct 22, 2025 •

edited

Loading

chrisb13 commented Oct 23, 2025 •

edited

Loading