Documentation: Improve clarity of which config variables are supported in each tool

[georgemccabe]

This came up from Discussion dtcenter/METplus#1638 where it was unclear if topo_mask was supported in Ensemble-Stat.
Here is the relevant info from the Slack discussion:

How can we make it more obvious to users what options are supported by each tool?

George McCabe
For #2, I saw that topo_mask was not listed in the Ensemble-Stat settings, but it was mentioned in the Settings common to multiple tools section saying:
topo_mask.flag may be set separately in each “obs.field” entry.
It was unclear to me if this would get parsed as part of the logic to read the field dictionary for obs data, or if it is only parsed if the topo_mask setting is supported at the top level of the specific tool.
It seems that there are settings common to multiple tools but it is not explicitly clear which tools. Perhaps we should have a comprehensive list of the settings that can be used for a given tool and provide a link to the relevant item in the "Settings common to multiple tools" section to avoid having duplicate information.
Alternatively, we may be able to get fancy with having the common variable descriptions as separate components (files?) that can be "included" in the same way that we organize the Release Guide content. I'm not sure if this would make the documentation more difficult for us to manage or not.

John Halley Gotway
Yeah, organizing this info is challenging, but I definitely agree that what we currently have isn't good enough. land_mask and topo_mask shouldn't even be in the settings common to multiple tools section, because they're not (at least yet)!
We could go with the "fancy includes" approach, where we split out into separate files the description of config options that need to appear in multiple places. Then we just link them in. We didn't have these options when the documentation existed as config file comments... thus the "settings common to multiple tools" approach.
We could replace the settings common to multiple tools with a description of the things that apply when reading gridded data, like convert(x) and censor_thresh/censor_val.

George McCabe
METplus has a glossary of all config variables which auto-generates a linkable section for each variable. Would it make sense to do something similar to this for the MET configs? I'm not sure how that would work if say there is a dictionary heading we want to link to and also a sub-variable of that dictionary that we also want to link to.
👍
1

George McCabe
That would avoid the need to have a separate file for each common config variable that we use to link. We just link to the appropriate section of the glossary.rst file. It seems like we may benefit from trying out a couple examples to see what works best before doing a massive overhaul.

George McCabe
These are some of the steps we would have to complete:
Determine a good approach to organizing common config variable info. Potential solutions include:
Separate RST files that contain section for each common config variable, then "..include" that those files in each tool's section.
Create a glossary similar to METplus config glossary and reference sections in that file (each linkable section header would be auto generated by the ..glossary syntax)
Create a comprehensive list for each MET tool with the config variables that are read by the tool
Update documentation for each tool to include the information using the new approach

George McCabe
If it isn't too complicated, I like the idea of using the includes so that each section for the MET tool has all of the information displayed and the user doesn't have to click around to different pages to get all of the info. The actual content would be in 1 place so changes to the content would be easy to maintain.

Describe the Enhancement

These are some of the steps we would have to complete:

• Determine a good approach to organizing common config variable info. Potential solutions include:
  • Separate RST files that contain section for each common config variable, then "..include" that those files in each tool's section.
  • Create a glossary similar to METplus config glossary and reference sections in that file (each linkable section header would be auto generated by the ..glossary syntax)
• Create a comprehensive list for each MET tool with the config variables that are read by the tool
• Update documentation for each tool to include the information using the new approach

Time Estimate

Estimate the amount of work required here.
Issues should represent approximately 1 to 3 days of work.

Sub-Issues

Consider breaking the enhancement down into sub-issues.

• Add a checkbox for each sub-issue here.

Relevant Deadlines

List relevant project deadlines here or state NONE.

Funding Source

Define the source of funding and account keys here or state NONE.

Define the Metadata

Assignee

• Select engineer(s) or no engineer required
• Select scientist(s) or no scientist required

Labels

• Select component(s)
• Select priority
• Select requestor(s)

Projects and Milestone

• Select Repository and/or Organization level Project(s) or add alert: NEED PROJECT ASSIGNMENT label
• Select Milestone as the next official version or Future Versions

Define Related Issue(s)

Consider the impact to the other METplus components.

• METplus, MET, METdatadb, METviewer, METexpress, METcalcpy, METplotpy

Enhancement Checklist

See the METplus Workflow for details.

• Complete the issue definition above, including the Time Estimate and Funding Source.
• Fork this repository or create a branch of develop.
  Branch name: feature_<Issue Number>_<Description>
• Complete the development and test your changes.
• Add/update log messages for easier debugging.
• Add/update unit tests.
• Add/update documentation.
• Push local changes to GitHub.
• Submit a pull request to merge into develop.
  Pull request: feature <Issue Number> <Description>
• Define the pull request metadata, as permissions allow.
  Select: Reviewer(s) and Linked issues
  Select: Repository level development cycle Project for the next official release
  Select: Milestone as the next official version
• Iterate until the reviewer(s) accept and merge your changes.
• Delete your fork or branch.
• Close this issue.