Feature #2558 tc_diag_docs

[JohnHalleyGotway]

Expected Differences

• Do these changes introduce new tools, command line arguments, or configuration file options? [No]
  
  If yes, please describe:
  

• Do these changes modify the structure of existing or add new output data types (e.g. statistic line types or NetCDF variables)? [No]
  
  If yes, please describe:
  

Pull Request Testing

• Describe testing already performed for these changes:
  
  Built the docs locally to ensure that they render well with no warnings.

• Recommend testing for the reviewer(s) to perform, including the location of input datasets, and any additional instructions:
  

  • Confirm that all automated tests runs with no differences flagged.
  • Please review the feature_2558_tc_diag_docs branch of the docs. Please review for typos and clarity. And please feel free to make any updates you'd like, particularly in the Introduction section.
  • I added several "notes" to indicate that TC-Diag is still under development as of MET version 11.1.0.
  • Note that this PR includes updates to the TC-Diag chapter and also updates the flowchart for version 11.1.0.

• Do these changes include sufficient documentation updates, ensuring that no errors or warnings exist in the build of the documentation? [Yes]

• Do these changes include sufficient testing updates? [Yes]
  None needed.

• Will this PR result in changes to the test suite? [No]
  
  If yes, describe the new output and/or changes to the existing output:
  

• Please complete this pull request review by [Thursday 6/22/2023].
  

Pull Request Checklist

See the METplus Workflow for details.

• Review the source issue metadata (required labels, projects, and milestone).
• Complete the PR definition above.
• Ensure the PR title matches the feature or bugfix branch name.
• Define the PR metadata, as permissions allow.
  Select: Reviewer(s)
  Select: Organization level software support Project or Repository level development cycle Project
  Select: Milestone as the version that will include these changes
• After submitting the PR, select Development issue with the original issue number.
• After the PR is approved, merge your changes. If permissions do not allow this, request that the reviewer do the merge.
• Close the linked issue and delete your feature or bugfix branch from GitHub.

[JohnHalleyGotway]

@jvigh thanks for making these updates to the docs in this commit. I reviewed them via RTD here.

I see that you:

1. Updated the intro section. Thanks for adding that background info. It reads well to me.
2. Added sub-sections to the config file section. We don't have this in the other chapters, but I do think this is a good change. That way we can provide direct links to specific parts of the config file. @jprestop please feel free to weigh in with any other feedback about this.

Note that I did just commit one edit to fix the number of underline characters used on line 104. You were short by one which threw and warning message and caused the documentation GHA workflow to fail. I expect the docs to render without warnings after that change.

[jvigh]

@johnhg Yeah, I was reading this and it said "subsections below", but then there were no headings. The only clue to readers that there was a new subsection were the horizontal rule lines. Then the reader would have to just dig into the text below the config section to try to understand what it was about. So I added headings. Modify them if they're too wordy or if there's a better name for the config section.

…

Message ID: ***@***.***>

[jprestop]

@jvigh and @JohnHalleyGotway, I also think that the addition of the subsection headers is a good change. Not only does it now provide direct links to specific parts of the config file, but it also seems more readable as well. Thanks @jvigh!

[jprestop]

Also, I added a comment to an existing issue to consider making the formatting the same across all config options for consistency.

[jvigh]

In this paragraph:

tc_diag_STORMID_ATCFID_YYYYMMDDHH_cyl_grid_DOMAIN.nc where STORMID is the 2-letter basin name, 2-digit storm number, and 4-digit year, ATCFID is the track model name, YYYYMMDDHH is the track initialization time, and DOMAIN is the domain name.

The ATCF nomenclature would be to call ATCFID 'TECH', where TECH is described as the "acronym for each objective technique", which could simply be called ATCF TECH ID for these purposes. But if MET uses ATCFID elsewhere, I think it's fine to leave as is. If not, it might be good to change ATCFID to TECH.

https://www.nrlmry.navy.mil/atcf_web/docs/database/new/abdeck.txt

[jvigh]

I have noted in a comment re: ATCFID vs. the ATCF's actual nomenclature of TECH. Apart from that, everything looks good. I will defer to @JohnHalleyGotway whether any changes are needed.

[JohnHalleyGotway]

Finalizing these TC-Diag documentation updates after...

1. Replacing "ATCFID" with "TECH".
2. Changing the destination branch from develop to main_v11.1.