Documentation issues (cpld_gridgen and doc links)

[gspetro-NOAA]

• I see that there is documentation for cpld_gridgen in the UFS_UTILS repo, but when I look at the documentation on Read The Docs (latest), it does not appear there.
• When I click on the documentation link in the cpld_gridgen section of the code (https://github.com/ufs-community/UFS_UTILS/blob/develop/sorc/cpld_gridgen.fd/docs/user_guide.md), it comes up with a 404 Not Found message.
• In general, when I click on the documentation links contained in the user_guide.md file for a given executable, I get a 404 Not Found message for that, as well. The link issue seems to be more generalized.

[GeorgeGayno-NOAA]

The user_guide.md files are used to create the Doxygen documentation. So, when viewed from the repository some links don't point at anything. As you pointed out here is an example

• https://github.com/GeorgeGayno-NOAA/UFS_UTILS/blob/develop/sorc/cpld_gridgen.fd/index.html

Users should refer to this documentation: https://ufs-community.github.io/UFS_UTILS/

[GeorgeGayno-NOAA]

The cpld_gridgen is not part of Read The Docs. Not every program is documented yet. Priority is given to those programs that are used by the SRW/MRW Apps.

Is cpld_gridgen used by the next SRW App release?

[GeorgeGayno-NOAA]

@gspetro-NOAA what should be done with this issue?

[gspetro-NOAA]

Hi George,

I'm not sure--the SRW App may not use cpld_gridgen, but it seems to build all of the UFS_UTILS executables, including that. I have emailed @chan-hoo to see if it is used in the AQM configuration at all. I was looking for a definition because I provide a brief definition in the SRW docs of every executable that the SRW App builds, regardless of whether it's used, since users will see it there if/when they check for a successful build and may wonder what it does.

If the user_guide.md pages will consistently lead to a 404 not found, it may be worth adding a note in the main README to that effect. Otherwise, as users go through the repo looking for documentation for code that may not be fully documented (as I did), they will come across a bunch of these 404 Not Founds. While these users may be few and far between, it's hard to predict in advance what kind of things users will decide to try, so in my mind, it's preferable to say upfront that this is a known "feature" of the repo. Just my two cents. :)

-- Gillian

[GeorgeGayno-NOAA]

@gspetro-NOAA - Concerning the broken links, see my example updates at 0b62d20. If users go to the chgres docs directory, there will be a README directing them to the official documentation. And I renamed user_guide.md to chgres_cube.md to discourage users from thinking it is a file they should be reading.

https://github.com/GeorgeGayno-NOAA/UFS_UTILS/tree/feature/srw_doc/sorc/chgres_cube.fd/docs

If you think this will work, I can update the other program's documentation directories in the same way.

[gspetro-NOAA]

@GeorgeGayno-NOAA That seems like a good solution to me! :)

Also, Chan-Hoo has said that AQM doesn't use cpld_gridgen, so to my knowledge, that executable is not used in the SRW App at this time and doesn't need to be prioritized for documentation.

[GeorgeGayno-NOAA]

The doxygen was created from the branch at 2fe2ece and viewed on rzdm. It looked ok.