Adding MPAS-Ocean documentation

[alicebarthel]

This includes the comprehensive MPAS-Ocean Users guide pdf (generated by @xylar), and a quick start guide.

[alicebarthel]

I plan to include templates of G- and C-case runscripts - which I have yet to clean up and test. Can you review the quick start guide for now?

[rljacob]

Note the linter fails. Those need to be fixed:

Error: components/mpas-ocean/docs/user-guide/index.md:125:388 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md009.md
Error: components/mpas-ocean/docs/user-guide/index.md:125:230 MD033/no-inline-html Inline HTML [Element: package] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md033.md

[alicebarthel]

Just reporting that I had issues with the G(MPAS-JRA1p5) case on Anvil, and both the G- and C-cases on pm. All using v3.0.0 and LR (IcoswISC30E3r5). I have not done a comprehensive survey to test all the meshes mentioned on all machines. @jonbob let me know if you need me to do that.

[xylar]

@mark-petersen, can you please merge https://github.com/MPAS-Dev/MPAS-Documents/pull/77 as soon as this PR is merged? I think it makes sense to keep it open until then in case we make further changes.

[mark-petersen]

@alicebarthel We need to add the following files:

components/mpas-ocean/docs/index.md
components/mpas-ocean/docs/tech-guide/index.md
components/mpas-ocean/docs/dev-guide/index.md

even if they are stubs with 'coming soon' on them. That way all the components have matching file names for the links. We have external documents and papers that we can link to within the tech and dev guides.

I can add that today or tomorrow. See examples on: https://github.com/E3SM-Project/E3SM/pull/6314/files https://github.com/E3SM-Project/E3SM/pull/6356/files

[mark-petersen]

@alicebarthel I added the files in the last post and pushed them to my fork https://github.com/mark-petersen/E3SM branch ocn/documentation commit 8884471d12.

You can see my new pages here:

• home page
• dev guide
• tech guide

If you agree you can grab my commit and add it to this PR.

[mark-petersen]

We would like to have this merge tomorrow morning so we are ready for the tutorial next week. If any reviewers have comments, please make them today. I gave everything a thorough read and revision, so it's OK if you don't have time.

[mark-petersen]

@rljacob, @xylar, @alicebarthel this has a 5.6MB file added to the E3SM repo. I don't like to add files that size to the repo. Plus there is an old version in commit 828061eb3b.

My preference is to make a zenodo entry and just add a link. It will be a new version but like this: https://zenodo.org/records/1246893 and it has a DOI.

Do you agree? @alicebarthel I can make those changes. I would need to edit the previous commits or (more easily) squash them to remove these pdfs from the history. Is that OK?

[rljacob]

Yes remove the pdf from this PR and the branch history. Yes a zenodo link is fine.

[mark-petersen]

User's guide is now here: https://zenodo.org/records/11098080

[mark-petersen]

All suggestions by @xylar and @vanroekel have been added. Large pdf file has been removed from history. I squashed the commits to make that easier to remove.

@rljacob and @jonbob this is now ready to merge (before the tutorial!)

[jonbob]

merged to next

[jonbob]

merged to master

[rljacob]

A few things had to be edited above this for the docs to appear with rest. I added that in https://github.com/E3SM-Project/E3SM/pull/6374