Describe the Task

Modify the existing "Documentation Overview" section to be "Documentation Overview and Conventions" in the METplus Contributor's Guide.

The majority of the documentation is created using the Sphinx documentation generator tool, which was originally created for Python documentation. The documentation is created using reStructuredText (rst).This link provides a brief introduction to reST concepts and syntax, intended to give authors enough information to create and modify the documents productively. We follow the conventions outlines in the link, along with some additional METplus Component specific conventions:

(There may be missing items from the Bold and Italics lists below.)
Bold

• Variables (e.g. MET_INSTALL_DIR, INPUT_BASE, METCALCPY_HOME, etc.)
• Filenames (line_defaults.yaml, contour_defaults.yaml, defaults.conf, etc.)
• Math equations
  use \mathbf
  Then put what you need bolded in brackets.
  1, 2, 3, 4, ... :math:\mathbf{2^{n-1}}
  Referencing math equations
  https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#role-math-numref

Italics:

• Paths / Directories
• If it is a full path and a file name, use italics. This was used a lot in METplotpy, example:
  $METPLOTPY_SOURCE/METplotpy/test/ens_ss/ens_ss.data
  Italics for values to options.

We should also probably specify outright things that we want to make sure people use from the link above. For example, defining chapters & sections, etc. in the following way, so that we don't have to go back and redo:

Here is the syntax from the RST docs (https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections):

# with overline, for parts (e.g. the RTD documentation for the component (i.e. docs/index.rst), each guide (e.g. User's Guide, Contributor's Guide) (i.e. docs/Users_Guide/index.rst, docs/Contributors_Guide/index.rst))
* with overline, for chapters
=, for sections
-, for subsections
^, for subsubsections
", for paragraphs

We'll have to take a look and see what else we want to include.

Check on the information currently included in that section such as "The following Sphinx modules are required to generate the necessary documentation" - those may not be accurate any longer.

============

The above items have been added and updated. 6/14/23 @lisagoodrich, @georgemccabe, @JohnHalleyGotway , @j-opatz, @DanielAdriaansen and @TaraJensen met to discuss adding the items in the "[METplus Sphinx Documentation Guide] (https://docs.google.com/document/d/1A-r-rE2SHB-jl29PblyuaetAG7Rqa2TmPxvFaWNCguY/edit)" into ReadTheDocs so all formatting documentation is in one location. (@jprestop was out of the office).

1. Some areas may need to be reworded to avoid plagiarism from the sphinx site.
2. Update "8.4.6. Build the Documentation Manually" and link it to "10.7. Building Sphinx Documentation Manually' so the information is in one place.
3. John HG requested having an example of how to render a math equation that uses an underline "_". Oftentimes this will render correctly in html but not correctly with a pdf. Use this ["H_RATE example] (https://github.com/dtcenter/MET/blob/develop/docs/Users_Guide/appendixC.rst#h_rate)".

Time Estimate

Estimate the amount of work required here.
1 to 3 days of work

Sub-Issues

Consider breaking the task down into sub-issues.

• Add a checkbox for each sub-issue here.

Relevant Deadlines

None

Funding Source

2792543

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

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.
• 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.