Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Documentation Overview and Conventions #2749

Open
7 of 24 tasks
lisagoodrich opened this issue Oct 25, 2024 · 0 comments
Open
7 of 24 tasks

Update Documentation Overview and Conventions #2749

lisagoodrich opened this issue Oct 25, 2024 · 0 comments
Assignees
Labels
alert: NEED ACCOUNT KEY Need to assign an account key to this issue component: documentation Documentation issue priority: low Low Priority requestor: METplus Team METplus Development Team type: task An actionable item of work
Milestone

Comments

@lisagoodrich
Copy link
Contributor

lisagoodrich commented Oct 25, 2024

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

Time Estimate

<1 day

Sub-Issues

Consider breaking the task down into sub-issues.

  • Add a checkbox for each sub-issue here.

Relevant Deadlines

None

Funding Source

TBD

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.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
alert: NEED ACCOUNT KEY Need to assign an account key to this issue component: documentation Documentation issue priority: low Low Priority requestor: METplus Team METplus Development Team type: task An actionable item of work
Projects
Status: 🟢 Ready
Development

No branches or pull requests

3 participants