Documentation: Develop an RST template for use cases, and update existing use cases to use the template

[DanielAdriaansen]

Describe the Enhancement

In order to streamline the look and feel of the use case pages, and improve efficiency of adding new use cases for developers, prepare a default use case template file in RST/Python (for sphinx-gallery). There will need to be one for met-tool-wrapper use cases and one for model-applications use cases. Once the templates are developed, update all existing use cases to utilize the template.

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

2792541

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

• Review projects and select relevant Repository and Organization ones or add "alert:NEED PROJECT ASSIGNMENT" label
• Select milestone to next major version milestone 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), Project(s), Milestone, and Linked issues
• Iterate until the reviewer(s) accept and merge your changes.
• Delete your fork or branch.
• Close this issue.

[DanielAdriaansen]

@georgemccabe I created this issue to help ensure we have a base template to work from when adding new use cases because during other work I've discovered use cases where someone obviously copy and pasted from another use case but didn't proof read good enough and there was leftover stuff in there from the use case it was copied from. My thinking was a stripped down version to start with, which would force the person adding the new use case to make sure they've added everything rather than possibly overlooking a section or leaving a section specific to another use case in there inadvertently.

When talking with Lisa, I vaguely remembered that when I did initial Sphinx work, I had exactly this but I couldn't find it. Searching email I found a thread with subject "feature_297_sphinx_transition ready for merge" where I say that I added this template. Then, I see in this commit:
aba2654

They were removed.

What do we think about having an RST/PY file template again, one each for met-tool-wrapper and model-applications to start from when adding a new use case? I'm not sure where they would go in the repository, but it looks like initially I just had them ignored during docs rendering but the actual files still existed in the repository.

[DanielAdriaansen]

@georgemccabe following up on this- wondering if you had a chance to review this or any thoughts.

[georgemccabe]

@DanielAdriaansen I think I originally removed the template file because I didn't think it was being used. Now that I understand its purpose I think it does make sense to include a template to prevent information from another use case from being included in another. Without fully understanding the use case it may be easy to miss them and it would be more clear that a section has not been modified if it contained the template text. However, some use cases contain additional sections that were not included in the original template such as Python embedding info or additional Python dependencies. We would have to get the superset of all sections with a note that the section should either be removed or replace the text with something like "N/A."

I think in the past developers of new use cases were not aware of the existence of the template so they would copy an existing use case and modify it. If we do this work we should update the contributor's guide to mention it.

[lisagoodrich]

I researched my notes. I got permission to start working on this but never got an account key. It looks like there is no account key. I'll be out of town for a week starting this Friday. I'd be happy to work on this when I get back.

[JohnHalleyGotway]

At the MET development meeting on Aug 30, 2023, we noted that the METplus New Use Case template should include specific information about MET version requirements. For example, python embedding of point observations logic was enhance in MET version 11.1.0 but running this AMDAR use case with MET version 11.0.1 produces a segfault.

The documentation for that use case should make it clear that it requires MET version 11.1.0 at minimum.

[lisagoodrich]

@georgemccabe, @DanielAdriaansen and @j-opatz I was talking with @jprestop about priorities and what I should start working next. She thinks this would be valuable to the user community. She noticed this was assigned to the beta-2 release, our current cycle. Would you have time to meet with me to get me started on this?
@TaraJensen could you provide an account key?

[georgemccabe]

I think where we last left off with this issue @j-opatz was going to review and come up with a template to use. We will need that template before we can update the existing use cases to use the same format.

[j-opatz]

I've created a draft template in Docs, link is provided here (available only to METplus team members).

There are some lingering questions, like what to do for met_tool_wrapper use cases (i.e. should those documents look different than normal use cases), as well as a potential introduction of new sections.

[lisagoodrich]

Thanks, @j-opatz!

I've got a few quick questions:

1. Am I just creating an .rst file that will only be linked to in the contributors guide?
2. What account should I charge? (I'll send Tara an email).

Next week is going to be busy for me so please let me know if I should be working on this instead of the MET headers #2716

[lisagoodrich]

@j-opatz I'm going through my github issues and this is still open. Could you confirm that I am just creating an .rst file that will only be linked to in the contributors guide?
I have an account to charge.
Thanks.

[jprestop]

Hi @lisagoodrich. The last correspondence about this was from @j-opatz via email on 2/7, where he said:

Thanks for the inquiry. I think as it stands, we are working out of the Docs template and getting a feel for what needs to be included. I'll have a bit more free time when I come back from PTO on the 26th so I think we can revisit this then. Once we're out of draft form you should be able to help with the revision work on existing use cases.

So, I think he, @georgemccabe, and @DanielAdriaansen have been working on a draft to provide to you. John O, George, and Dan, could you please provide Lisa with a status update?

[DanielAdriaansen]

I have not been working with anyone on this. I defer to @j-opatz.

[DanielAdriaansen]

As a note-

I added something I found useful today when working on docs for a use case. A table of contents, using this syntax:

##############################################################################
# .. contents::
#    :depth: 1
#    :local:
#    :backlinks: none

It gave the HTML appearance like this:

This provides a nice clickable entry for users and doesn't result in a ton of scrolling, especially for use cases that have huge literalincludes from Python embedding or giant METplus conf files.

Following from:
https://stackoverflow.com/a/69571091

[lisagoodrich]

Thanks, @DanielAdriaansen I didn't know about this feature. It definitely streamlines things. I'll defer to others to let me know when they'd like to use this or not. Here is a link to the develop page so others can see the new image vs the current version: https://metplus.readthedocs.io/en/develop/generated/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI.html

[jprestop]

@j-opatz When you are ready for the PR, please consider @DanielAdriaansen, @lisagoodrich, and @georgemccabe as reviewers.

[j-opatz]

Work has begun on a feature branch for this template under feature_918_add_use_case_template.

This work intends to add the reviewed template in Docs form to this section, effectively replacing the bullet points with the template itself.