Documentation: Develop an RST template for use cases

[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.
UPDATE on 20241028: There was no separate template made for the met_tool_wrappers. While the idea had originally to create two templates (one for users, one for demo of tools), additional conversations in several meetings showed that most of the team thought it was unnecessary and may cause confusion to users which template to use.

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.

[lisagoodrich]

Hi @j-opatz, I dumped this into google doc to find typos and grammar stuff. I found the below extra "e" in "case"

line 979 Disk space usage of the use casee exceeds the available space in the

Since it wasn't in the documentation that you changed, it didn't show up in the fancy editing window.

I found one other typo and marked it. I didn't read through the documentation. Please let me know if I should do something else.

[georgemccabe]

The template was created in PR #2690, but we still need to review and update the existing use cases to use the template format.

[jprestop]

The template was created in PR #2690, but we still need to review and update the existing use cases to use the template format.

@georgemccabe, @DanielAdriaansen While this issue is titled "Documentation: Develop an RST template for use cases, and update existing use cases to use the template #918". I'm wondering what you think of changing the title to "Documentation: Develop an RST template for use cases" and creating a new issue for "Documentation: Update existing use cases to use the template". I can see a case for keeping them together but also for separating them. There are already a lot of comments on this issue and I could see more questions coming with a possible new issue. The account key was apparently "2792541" as listed in the issue, but will now be NRL (which, of course, we could just change). Any preferences on keeping or separating?

[georgemccabe]

@jprestop, I don't have a strong preference. I do see the benefit of splitting it up into 2 issues since we have completed the first part in beta6 and there is a lot of discussion already on this issue.

[jprestop]

Thanks for your feedback @georgemccabe. I'll wait for preferences from @DanielAdriaansen too, particularly since you don't have a strong preference, before proceeding.

[DanielAdriaansen]

Please mark this issue as completed, change this issue to the proposed title, open a new issue for the second part of the work using the proposed title, reference this issue, assign the NRL account key to the new issue, and put it on the NRL project board. I would assign it to the MET-12.1/6.1 release cycle, not this release.

I agree any new discussion is best captured under a dedicated issue to avoid the conversation getting too involved, and since this work was done under different support. Thanks @jprestop!

[jprestop]

Thanks @DanielAdriaansen! I noticed that you said to assign it to the MET-12.1/6.1 release cycle, not this release. @lisagoodrich would likely be able to start on it soon, so I want to confirm that you do not want it assigned to this release cycle?

[DanielAdriaansen]

Thanks @DanielAdriaansen! I noticed that you said to assign it to the MET-12.1/6.1 release cycle, not this release. @lisagoodrich would likely be able to start on it soon, so I want to confirm that you do not want it assigned to this release cycle?

That's correct, please use MET-12.1/6.1 release cycle. I think given the release date is before the end of this period of performance for NRL, it's probably advisable to focus on doing this work rather than adding additional items for this release. I suppose we can always assign it to the next release but if it does manage to get finished then it will end up being included? But I don't feel a strong need to push for it.

[jprestop]

Thanks for chatting with me @DanielAdriaansen. As we discussed the new issue Documentation: Update existing use cases to use the template #2741 has been created. I have referenced this existing issue (which I will close with this comment), assigned the NRL account key to the new issue, and put it on the NRL project board. I have also assigned it to the METplus-6.1 release milestone with NO project cycle selected.

[jprestop]

@georgemccabe Just a note since we completed this issue in beta6, and I recently renamed and closed this issue. I have added this issue to the release notes for beta6.