Need documentation for NEMS as part of UFS MR Weather app release

[ligiabernardet]

As part of the documentation for the upcoming MR Weather App release, we would like to provide a link to an external documentation describing NEMS (or at least the aspects of NEMS that will be used in this release). Existing documentation needs to be updated:

• [https://www.emc.ncep.noaa.gov/projects/nems-doc]
• [https://noaa-emc.github.io/NEMS_doc/index.html]

We need additional/updated information about NEMS pertaining to the aspects below. Note that the documentation on the various aspects can be combined onto a cohesive document (so not necessarily four separate documents).

1. Developer’s guide – code management for contributing development
2. Technical Documentation – code structure, architecture, how to add capabilities
3. Scientific Documentation – scientific aspects of the code

Given the tight timeline for the release, it is possible that we can accomplish only a subset of this, which can be augmented in future releases.

Regarding the framework for preparing and displaying the documentation, we understand that the UFS is a diverse system and that individual community software packages will have their own methods to create and display documentation.Nonetheless, please consider the following:

• The documentation is housed the same repository as the code (in this case, https://github.com/NOAA-EMC/NEMS)
• Doxygen for Fortran-embedded documentation.
• Sphinx for rest of documentation.
• ReadTheDocs to display the HTML.

The documentation release team is available to help with the logistics if you need.

@RatkoVasic-NOAA @arunchawla-NOAA

[ligiabernardet]

We need documentation on input file model_configure and how users can manipulate it.

[ligiabernardet]

@arunchawla-NOAA @RatkoVasic-NOAA

Arun and Ratko, can you please let me know whether you plan to provide NEMS documentation to go along with the upcoming MRW app release? This would be helpful, but it is not a show stopper because for this release only a small part of NEMS is used.

My understanding is that NEMS owns the main program and the driver. For this release, the NEMS documentation can be simple (just document that the main program and NUOPC driver are part of NEMS).

For future UFS releases, more NEMS documentation will be necessary. So, my suggestion is that we start a simple Sphynx-based documentation with .rst files in the NEMS repo/branch for this release, and make it more sophisticated as time goes on. Please let me know your thoughts.

[arunchawla-NOAA]

@ligiabernardet

NEMS documentation was moved to a separate repository

https://github.com/NOAA-EMC/NEMS-doc

because it contains a lot of image files that was making the cloning of the repo really slow. I am not a fan of documentation sitting separately from the repo but with png files this was the solution. Do you have an alternative solution ?

Here is the relevant html page

https://noaa-emc.github.io/NEMS_doc/index.html

[ligiabernardet]

@arunchawla-NOAA @RatkoVasic-NOAA I do not have a solution for how to house image files without slowing down the cloning. But I have a question: why are so many images needed in the documentation? They do not seem to be displayed with the HTML (https://noaa-emc.github.io/NEMS_doc/documentation.html). Do we really need the images?

There is very valuable information at https://noaa-emc.github.io/NEMS_doc/documentation.html, but a portion of it is out-of-date. To my knowledge, no resources have been allocated to updating the NEMS documentation. I would like your recommendation on whether this should be linked to the release documentation, or whether this will just confuse the readers. Examples of updates needed include references to SVN, references to VLab, instructions for Theia and not for Hera, etc.

[ligiabernardet]

@ArunChawla has let us know that they have put together the parts that will go into the main documentation. Clean up will happen this week and then we will do a PR back to the NEMS repo. This documentation will live with the NEMS repo and all figures and old materials have been removed.

[arunchawla-NOAA]

@ligiabernardet and @llpcarson. NEMS documentation was cleaned up and a PR to the NEMS public release branch was made by @MinsukJi-NOAA. The link is here

https://noaa-emc.github.io/NEMS_doc/index.html

[arunchawla-NOAA]

@ligiabernardet and @llpcarson with the first pass of NEMS documentation complete we will close this issue now. You should be able to link to that documentation