how to create and edit ACCESS-rOM3-panan documentation

[chrisb13]

Preview link

HERE

---

As part of this discussion, this is the start of making a fully supported ACCESS-rOM3-panan documentation. ping @claireyung @helenmacdonald.

Here's some steps to edit this on a terminal:

git clone [email protected]:ACCESS-NRI/access-om3-configs.git
cd access-om3-configs
git branch -vva
git checkout remotes/origin/cbull/561-ice-shelf-maindocs
git switch -c cbull/561-ice-shelf-maindocs
#edit the new /access-om3-configs/documentation/docs/pages/IceShelves.md
#make changes
git add IceShelves.md
git commit -m 'message'
git push --set-upstream origin cbull/561-ice-shelf-maindocs

A PR-preview will then appear in this draft PR.

Alternatively just edit IceShelves.md online here and use GitHub to commit.

For community contributions they should make a fork and then merge back into this branch (I think!).

@claireyung, I think for now feel free to put all Ice Shelf documentation in here, we can wait till @atteggiani gets back to include configuration specific information in a "stub".

NB: not looking for a review just yet!

[edoyango]

Hi @chrisb13, @minghangli-uni, @claireyung, @manodeep, I've added some notes on optimization to the iceshelf page. Please comment or add stuff if I've missed anything, gotten anything wrong, or something needs clarifying!

[minghangli-uni]

Thanks @edoyango - looks like there’s an issue with the rendering:

Also, feel free to rebase onto the latest commit when you’re ready.

[chrisb13]

Hi @chrisb13, @minghangli-uni, @claireyung, @manodeep, I've added some notes on optimization to the iceshelf page. Please comment or add stuff if I've missed anything, gotten anything wrong, or something needs clarifying!

Amazing, thanks @edoyango! Re: this -- Seems to be rendering okay now after your recent commits.

[chrisb13]

@claireyung so awesome to see this coming together!

On a small piece of interim feedback, can I suggest you also include the very detailed instructions in this doc' as well? They can just be included verbatim at this point.

I'm referring to this line:

Detailed step-by-step instructions are provided here

I mentioned this to @helenmacdonald and having these kinds of detail level instructions is super helpful for other regional users interested in using om3 output, so I think it's really valuable to include here. (Some of this content will eventually be moved to a "stub" so that it only refers to this configuration but that's something we'll implement a bit later.)

[chrisb13]

H'm the PR-preview seems to be failing...

Switched to a new branch 'davide/527-include_stubs'
branch 'davide/527-include_stubs' set up to track 'origin/davide/527-include_stubs'.
SITE_URL=https://access-nri.github.io/access-om3-configs/pr-preview-706 mkdocs build -f mkdocs.yml -d /home/runner/work/access-om3-configs/access-om3-configs/website/pr-preview-706
ERROR - Config value 'plugins': The "include-configuration-stubs" plugin is not installed

Aborted with a configuration error!
Error: Process completed with exit code 1.

I think it might be related to having an open PR over here but I'll let @atteggiani correct me...

[claireyung]

@chrisb13 I directly copied my notes into a new subpage. Would you please be able to do the merging again as I think I broke the rendering now

Edit: ok thanks for the insight

[chrisb13]

@chrisb13 I directly copied my notes into a new subpage. Would you please be able to do the merging again as I think I broke the rendering now

Edit: ok thanks for the insight

Yeah so I think the preview is likely broken for these reasons.

But looking at your commit 8e84f3c, you need to also update the mkdocs.yml file. Have a look at these lines, I suggest having a new Panan category so you can have sub-pages, you can model it on the WW3 example that I've highlighted in this last link.

[claireyung]

Woops sorry I forgot to add the edits to the commit. Hopefully it's correct syntax but I can't really tell without the preview :)

[atteggiani]

I think it might be related to having an open PR over here but I'll let @atteggiani correct me...

Correct!

[chrisb13]

Okay, can we please merge it then? Not withstanding the two small queries in this comment (removing Release-mc_25km_jra_ryf.md and lower case for Dev-mc_25km_jra_ryf.md), I think it's ready to go?

[atteggiani]

I just replied to those comments.

[chrisb13]

@claireyung, we just merged, so seems to be working now:

• https://access-om3-configs.access-hive.org.au/pr-preview-573/pages/IceShelves/
• https://access-om3-configs.access-hive.org.au/pr-preview-573/pages/Detailedpananinstructions/
  Had to make a silly commit (2ca89fb) to make it build again. Look ok?

[atteggiani]

@claireyung, we just merged, so seems to be working now:

• https://access-om3-configs.access-hive.org.au/pr-preview-573/pages/IceShelves/
• https://access-om3-configs.access-hive.org.au/pr-preview-573/pages/Detailedpananinstructions/
  Had to make a silly commit (2ca89fb) to make it build again. Look ok?

For future cases in which you want to rerun a website build workflow using the same commit (like in this case), you can siply re-run the workflow that failed without needing to issue a new commit.
Or alternatively (in cases where the workflow itself has been changed and needed to be updated - but it is not this current case), you can git commit --amend --no-edit and git push --force-with-lease without needing to issue a "fake" commit.

[chrisb13]

you can siply re-run the workflow that failed without needing to issue a new commit.

Oh right, you mean like clicking this button [1]? Hadn't seen that!

[1]

[chrisb13]

This link is broken. Perhaps this was the file that was meant:
https://github.com/claireyung/mom6-panAn-iceshelf-tools/blob/main/generate-obcs/ACCESS-OM2_panan_boundary_forcing_8km.ipynb
@claireyung ?

(Just out of curiosity, is generate-obcs/ACCESS-OM2_panan_boundary_forcing_25km.ipynb the file that was used for the 25km equivalent config? And perhaps this generate-obcs/BYO-domain.ipynb is from the regional mom6 workflow?)

[claireyung]

Sorry, yes you are correct, that is the correct link. And 25km is for the 25km config, and yes the BYO domain was an old attempt of mine to use the regional mom6 workflow which I did not complete.

[chrisb13]

Okay sweet, I've made a suggested edit.

[chrisb13]

@anton-seaice I'm aware that you're cleaning up the docs at the moment, perhaps we should aim to merge this soon? Maybe the same time that we approve the panan pr? Conveniently, it's not a stub but maybe should be in the configuration section?

ping'ing @helenmacdonald as I think she has an interest in the how to create a regional config' bits...?

[anton-seaice]

Yeah IceShelves.md is appropriate for Configurations section, and the instructions could maybe go in the Contributing section. Should not be impacted by any refactoring to remove stubs or use read the docs

[chrisb13]

Yeah IceShelves.md is appropriate for Configurations section, and the instructions could maybe go in the Contributing section. Should not be impacted by any refactoring to remove stubs or use read the docs

Yeah I think that makes sense. Particularly whilst there isn't a similar regional repo'.

@helenmacdonald perhaps you'd be able to review the instructions / move it to Contributions?

[chrisb13]

Yeah IceShelves.md is appropriate for Configurations section, and the instructions could maybe go in the Contributing section. Should not be impacted by any refactoring to remove stubs or use read the docs

Yeah I think that makes sense. Particularly whilst there isn't a similar regional repo'.

@helenmacdonald perhaps you'd be able to review the instructions / move it to Contributions?

@helenmacdonald any thoughts on this? Would like to get this sorted to coincide with the upcoming alpha release.

Happy to coordinate with you if that's useful.

[chrisb13]

@atteggiani so I think I did as you described but now it's not rendering the page in the TOC despite being listed there. I also get a 404 on the landing page. Any ideas?

Perhaps I messed up resolving the many conflicts?

[atteggiani]

@atteggiani so I think I did as you described but now it's not rendering the page in the TOC despite being listed there. I also get a 404 on the landing page. Any ideas?

Your "not rendering the page in the TOC" link points to https://access-om3-configs.access-hive.org.au/pr-preview-573 which is the old URL for PR previews. The preview now is at https://access-om3-configs.access-hive.org.au/pr-previews/573

I removed the comment with the old link.

[chrisb13]

@claireyung. @helenmacdonald and I have just been going over the docs, you can see the render here.

From this process, I've noticed that there's this c0d8171 commit which looks to contain details of how you've been running the model? Should we also be including that in the config' doc? Very happy to do so but it's up to you. Relatedly, have there been any other instruction changes that we should be aware of? (Rather lucky, I spotted c0d8171.)

If you'd like to include it, can you please add the file to this branch (and remove it from claireyung:dev-MC_4km_jra_ryf+regionalpanan+isf+draft), this will keep your authorship.

[claireyung]

Hi @chrisb13
Thanks, the docs look great!

One comment - the configuration page name is IceShelves but neither of the files actually relate to the ice shelf config as they both were written for the pan-Antarctic om3 config without ice shelves. Should that be renamed to pan-Antarctic?

Related - I'm very happy to add the ice shelf how-to-run instructions in the docs (latest version here , but wondering where it should go given there is no other documentation yet on the ice shelf config? I started writing some for mom6-sis2 ice shelves a while ago, but haven't gotten around to it for the nuopc version yet, sorry!

[chrisb13]

One comment - the configuration page name is IceShelves but neither of the files actually relate to the ice shelf config as they both were written for the pan-Antarctic om3 config without ice shelves. Should that be renamed to pan-Antarctic?

Great point! Now done 3182b77. Rendered version.

Related - I'm very happy to add the ice shelf how-to-run instructions in the docs (latest version here , but wondering where it should go given there is no other documentation yet on the ice shelf config?

I've made a placeholder in this branch in commit 3182b77 (access-om3-configs/documentation/mkdocs.yml). Can you please add your file to this Run ISF location:

        - pan-Antarctic:    
              - Overview: pages/configurations/pan-Antartic/Overview.md
              - Detailed: pages/configurations/pan-Antartic/Detailedpananinstructions.md
              - Run ISF: pages/configurations/pan-Antartic/run_panan_isf.md

(You can see that the run isf link here currently 404s)

I started writing some for mom6-sis2 ice shelves a while ago, but haven't gotten around to it for the nuopc version yet, sorry!

This is a PR and I think we want to (eventually) have some documentation for both with / without ice shelves so I don't think it hurts to have it now.

@helenmacdonald has been reviewing this, so might want to chime in on what's best. Perhaps she's across what changes are needed for the NUOPC version? (We try to keep docs as short as possible but as long as necessary.)

[helenmacdonald]

I started writing some for mom6-sis2 ice shelves a while ago, but haven't gotten around to it for the nuopc version yet, sorry!

This is a PR and I think we want to (eventually) have some documentation for both with / without ice shelves so I don't think it hurts to have it now.

@helenmacdonald has been reviewing this, so might want to chime in on what's best. Perhaps she's across what changes are needed for the NUOPC version? (We try to keep docs as short as possible but as long as necessary.)

mom6-sis2 ice shelves notes are mostly about how to create the files (which is relevant to the NUOPC version) with just a little bit of not-nuopc specific bits. I think it is relevant and is a similar level of detail that is being included for non ice-shelfs so a useful document to have around (although the non-nuopc sections would need modifying to make them nuopcs based before releasing).

[chrisb13]

Thanks 60ff214 @claireyung, looks good.

I started writing some for mom6-sis2 ice shelves a while ago, but haven't gotten around to it for the nuopc version yet, sorry!

mom6-sis2 ice shelves notes are mostly about how to create the files (which is relevant to the NUOPC version) with just a little bit of not-nuopc specific bits. I think it is relevant and is a similar level of detail that is being included for non ice-shelfs so a useful document to have around

Okay, great. Sounds like we have consensus on this. How would you both like to proceed? One option is that we add it to this PR and then perhaps @helenmacdonald could have a look at the non-NUOPC bits with feedback from @claireyung when things are unclear?

If this is agreeable, @claireyung can you please commit the file to this branch.

Open to other suggestions.

[chrisb13]

751016f ❤️ !

[claireyung]

Hi, i've updated my wiki with a nuopc version here https://github.com/claireyung/mom6-panAn-iceshelf-tools/wiki/ACCESS%E2%80%90OM3-config-with-ice-shelves-%E2%80%90-input-files-and-config-details and copied it into this branch in the above commit.

Some of the links in the page refer to pr previews of the panan no-ice shelf instructions so that probably needs to be fixed. I also added a bit of background overview of the config, and a few references.

Also, please note the instructions were sort of reverse-engineered because I didn't make the files in such a linear manner. They very likely are incomplete or have steps that don't work. Probably it would be good if someone tested the whole process on a new resolution so we can see what instructions don't work.... but that's also a big task so not sure if worth doing.

[chrisb13]

@helenmacdonald / @claireyung, feel free to tweak the headings I came up with in this 169eabc.

As in:
pan-Antarctic

• Overview
• Detailed noISF
• Detailed ISF
• Run ISF