Update Documentation Overview and Conventions

[lisagoodrich]

Describe the Task

Addition 1

Add "include" section to the documentation before the Literal Include section.

Please use the following description with the title "Include Text From a File":
The "include" directive reads a text file. It will include the information from the text file in the page where it is referenced. In this example, the "include" directive:

.. include:: existing_builds.rst

adds the text in the existing_builds.rst into the METplus Release Information chapter. Note that this directive is not visible in viewing the GitHub release-notes.rst file but it is visible by in viewing the raw version of that file. In this example, the existing_builds.rst file is located in the same directory as the release-notes.rst file. If the existing_builds.rst file were located in a different file, a relative path to the file should be provided.

See Including an External Document Fragment for more information about the "include" directive.

Lisa's Notes:
Using "include" will seamlessly transition the "included" documentation file into the new page. There will be no separate text boxes. This feature was used frequently in the Release Notes. This can keep the need to update documentation to a minimum (Julie asks, why do you say that it can keep the need to update the documentation to a minimum? I don't understand). In this example, the "include" adds the existing_builds.rst file into the Release Notes. On the GitHub web page
It is also important to note that the Existing Builds section is nowhere to be seen unless the raw section is opened and viewed. See line 26.

Video for how to get link: https://github.com/user-attachments/assets/ed3da419-904b-47c6-b550-b74884a44d5d

Also note, if the file is in a different directory, such as the Release Notes, the directory path must be provided with the "include" statement.

Add a code block to show the "include" statement.

Addition 2

Write up the use of Admonitions for the METplus Tutorial section.

Note that the admonition directive is the same color blue as the Note directive, so we decided to change the color of the admonition directive. Doing this required the following entries in the docs/_static/custom.css file:

/* Custom color for the admonition directive which allow the user to specify titles (e.g. Sample Output, File Contents) */
.admonition.admonition-default,
.admonition:not(.note):not(.warning):not(.danger):not(.tip):not(.important):not(.caution):not(.attention),
.rst-content .admonition-default,
.rst-content .admonition:not(.note):not(.warning):not(.danger):not(.tip):not(.important):not(.caution):not(.attention) {
    background-color: #f3e8ff; /* Very light purple/lavender background */
    border-color: #9b59b6;     /* Medium purple border */
}

.admonition.admonition-default > .admonition-title,
.admonition:not(.note):not(.warning):not(.danger):not(.tip):not(.important):not(.caution):not(.attention) > .admonition-title,
.rst-content .admonition-default > .admonition-title,
.rst-content .admonition:not(.note):not(.warning):not(.danger):not(.tip):not(.important):not(.caution):not(.attention) > .admonition-title {
    background-color: #9b59b6; /* Medium purple title background */
    color: white;              /* White text for best readability against purple */
}

See the example in the METplus-Tutorial at this location, however, note that location is currently a feature branch and will eventually disappear and get merged into a different branch.

Addition 3

Please note under the bold section and links section that if a section is bolded, an internal link won't work. This was discovered during the METplus training tutorial work. Sections were bolded and the links within them didn't work.

Time Estimate

<1 day If more than a day let Michelle know.

Sub-Issues

Consider breaking the task down into sub-issues.

• Add a checkbox for each sub-issue here.

Relevant Deadlines

None

Funding Source

2702701 (NCAR base)

Define the Metadata

Assignee

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

Labels

• Review default alert labels
• Select component(s)
• Select priority
• Select requestor(s)

Milestone and Projects

• Select Milestone as a METplus-Wrappers-X.Y.Z version, Consider for Next Release, or Backlog of Development Ideas
• For a METplus-Wrappers-X.Y.Z version, select the METplus-Wrappers-X.Y.Z Development project

Define Related Issue(s)

Consider the impact to the other METplus components.

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

Task 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.
• Add any new Python packages to the METplus Components Python Requirements table.
• For any new datasets, an entry to the METplus Verification Datasets Guide.
• 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 Development issue
  Select: Milestone as the next official version
  Select: METplus-Wrappers-X.Y.Z Development project for development toward the next official release
• Iterate until the reviewer(s) accept and merge your changes.
• Delete your fork or branch.
• Close this issue.