Feature 836 rtd release doc

docs/Contributors_Guide/add_use_case.rst

@@ -150,7 +150,7 @@ would look something like this::
 
 The content of this file is rendered above the icons for the use cases in this
 category in the User's Guide > METplus Use Cases >
-`Model Applications <https://dtcenter.github.io/METplus/latest/generated/model_applications/index.html>`_
+`Model Applications <https://metplus.readthedocs.io/en/latest/generated/model_applications/index.html>`_
 page.
 
 Add Sphinx Documentation File
@@ -179,7 +179,7 @@ In the corresponding documentation category directory
       a list of possible keywords to use (Note: The link text for the
       keywords must match the actual keyword exactly or it will not
       show up in the search, i.e. **ASCII2NCToolUseCase** must match
-      https://dtcenter.github.io/METplus/search.html?q=**ASCII2NCToolUseCase**
+      https://metplus.readthedocs.io/en/latest/search.html?q=**ASCII2NCToolUseCase**
 
     * Add an image to use as the thumbnail (if desired). Images can be added
       to the docs/_static directory and should be named <category>-<conf>.png
@@ -197,9 +197,23 @@ In the corresponding documentation category directory
     avoid ending a line with this character to avoid generating warnings in the
     documentation.
 
+Accessing the Documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Build the Documentation
-^^^^^^^^^^^^^^^^^^^^^^^
+It is important to ensure that the new use case files is displayed and the
+formatting looks correct. Prior to the release of METplus v4.0.0 contributors
+were required to build the documentation manually.  However, the METplus
+components now use Read the Docs to build and display the documentation. For
+more information on how to view the newly added use case, see the 
+:ref:`Read the Docs METplus Documenation <read-the-docs>`.  Contributors can
+still build the documentation manually if desired. See the
+:ref:`Build the Documentation Manually <manual-build>` section below for more
+information.
+
+.. _manual-build:
+
+Build the Documentation Manually
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Build the documentation and ensure that the new use case file is
 displayed and the formatting looks correct. The Python packages sphinx,

docs/Contributors_Guide/documentation.rst

@@ -5,25 +5,20 @@ Viewing METplus documentation
 _____________________________
 
 The METplus documentation (beginning with version 3.0) is available
-`online <https://dtcenter.github.io/METplus>`_.
-
-
+`online <https://metplus.readthedocs.io/>`_.
 
 
 Doxygen Source Code Documentation
 _________________________________
 
-The source code documentation is found
-`here <https://dtcenter.github.io/METplus/doxygen>`_.
-
+The source code documentation is coming soon.
 
 
 Documentation Overview
 ______________________
 
 The majority of the documentation is created using the Sphinx documentation
-generator
-tool, which was originally created for Python documentation.
+generator tool, which was originally created for Python documentation.
 The documentation is created using
 `reStructuredText (rst) <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
 
@@ -44,9 +39,9 @@ Contributor's Guide.
 Description of Documentation Directories
 ________________________________________
 
-Core documentation is divided into two sections: the User's Guide and
-Contributor's Guide, both of which reside under the *METplus/docs*
-directory, with files ending in .rst.
+Core documentation is divided into four sections: User's Guide, Contributor's
+Guide, Release Guide, and Verification Datasets Guide all of which reside
+under the *METplus/docs* directory and contain files ending in .rst.
 
 
 Documentation for the use cases is found in the following directories:
@@ -83,9 +78,16 @@ To determine where to add new documentation:
 * The User's Guide for any instructions or details that will enable a user
   to run/use the use case and/or new code.
 
-* The Contributor's Guide for any instructions for instructions on
-  creating/constructing the new code.
+* The Contributor's Guide for instructions on creating/constructing new
+  code.
 
+* The Release Guide for instructions for creating software releases for any
+  METplus component, including official, bugfix, and development releases.
+
+* The Verification Datasets Guide for any relevant "truth" datasets, including
+  data from satellite platforms (geostationary and polar orbiting), gridded
+  analyses (global and regional), station or point-based datasets (global and
+  regional), and radar networks.
 
 Use cases that have only one MET tool/METplus wrapper:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -115,10 +117,12 @@ Use cases that use more than one MET tool/METplus wrapper:
 * The model_applications directory contains subdirectories that
   are based on the following categories:
 
+  * air_quality_and_comp
   * climate
   * convection_allowing_models
   * cryosphere
   * data_assimilation
+  * marine_and_coastal  
   * medium_range
   * precipitation
   * s2s (sub-seasonal to seasonal)
@@ -157,25 +161,90 @@ Contributor's Guide:
 * Modify any of the affected sections from the
   *METplus/docs/Contributors_Guide* directory:
 
-  * add_use_case.rst (How to add new use cases.)
-  * basic_components.rst (The basic components of a METplus wrapper.)
-  * coding_standards.rst (The coding standards currently in use.)
+  * add_use_case.rst (How to add new use cases)
+  * basic_components.rst (The basic components of a METplus wrapper)
+  * coding_standards.rst (The coding standards currently in use)
   * conda_env.rst  (How to set up the conda environment for
-    running METplus.)
-  * create_wrapper.rst (How to create a new METplus wrapper.)
-  * deprecation.rst (What to do to deprecate a variable.)
-  * documentation.rst (Describing the
-    documentation process and files.)
+    running METplus)
+  * continuous_integration.rst (How to set up a continuous integration
+    workflow)  
+  * create_wrapper.rst (How to create a new METplus wrapper)
+  * deprecation.rst (What to do to deprecate a variable)
+  * documentation.rst (Describing the documentation process and files)
   * github_workflow.rst (A description of how releases are made,
-    how to to obtain source code from the GitHub repository.)
+    how to to obtain source code from the GitHub repository)
   * index.rst (The page that shows all the 'chapters/sections'
-    of the Contributor's Guide.)
+    of the Contributor's Guide)
   * testing.rst (A description of how to set up testing the
-    wrapper code.)
+    wrapper code)
 
+Release Guide:
+~~~~~~~~~~~~~~
 
-Building Sphinx Documentation
-_____________________________
+Coming soon!
+
+Verification Datasets Guide:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Coming soon!
+
+.. _read-the-docs:
+
+Read the Docs METplus Documentation
+___________________________________
+
+The METplus components use `Read the Docs <https://docs.readthedocs.io/>`_ to
+build and display the documentation. Read the Docs simplifies the
+documentation process by building, versioning, and hosting the documentation.
+
+Read the Docs supports multiple versions for each repository. For the METplus
+compoents, the "latest" version will point to the latest official (stable)
+release. The "develop" or "development" version will point to the most up to
+date development code. There may also be other previous versions of the
+software available in the version selector menu, which is accessible by
+clicking in the bottom left corner of the the documentation pages.
+
+Automation rules allow project maintainers to automate actions on new branches
+and tags on repositories.  For the METplus components, documentation is
+automatically built by Read the Docs when a new tag is created and when a
+branch is created with the prefix:
+
+  * feature (e.g. feature_836_rtd_doc)
+
+  * bugfix (e.g. bugfix_1716_develop_perc_thresh)
+
+The documentation of these "versions" are automatically hidden, however, the
+documentation can be accessed by directly modifying the URL. For example, to
+view "feature_836_rtd_doc" for the METplus repository the URL would be:
+
+  **https://metplus.readthedocs.io/en/feature_836_rtd_doc**
+
+  (Note that this link is not valid as this branch does not currently exist,
+  however contributors can replace the "feature_836_rtd_doc" with the
+  appropriate branch name.)
+
+Read the Docs will automatically delete the documentation for a feature
+branch and a bugfix branch when the branch is deleted.
+
+Documentation for each METplus component can be found at the links below:
+
+* `METplus <https://metplus.readthedocs.io/>`_
+* `MET <https://met.readthedocs.io/>`_  
+* `METcalcpy <https://metcalcpy.readthedocs.io/>`_
+* `METdatadb <https://metdatadb.readthedocs.io/>`_
+* `METexpress <https://metexpress.readthedocs.io/>`_
+* `METplotpy <https://metplotpy.readthedocs.io/>`_
+* `METviewer <https://metviewer.readthedocs.io/>`_
+
+
+Building Sphinx Documentation Manually
+______________________________________
+
+Documentation does not have to be built manually as it is automatically
+generated by Read The Docs.  See the
+:ref:`Read the Docs section <read-the-docs>` for further information.
+However, contributors can still build the documentation manually if
+desired.
 
 .. note::
 
@@ -193,34 +262,29 @@ enter the following:
 
 This script does the following:
 
-* Builds the Sphinx documentation.
-* Builds the doxygen documentation.
-* Removes unwanted text from use case documentation.
-* Copies doxygen files into _build/html for easy deployment.
+* Builds the Sphinx documentation
+* Builds the doxygen documentation
+* Removes unwanted text from use case documentation
+* Copies doxygen files into _build/html for easy deployment
 * Creates symbolic links under Users_Guide to the directories under
-  'generated' to preserve old URL paths.
+  'generated' to preserve old URL paths
 
 The html files that are created can be found in the *METplus/docs/_build/html*
 directory.  The web browser can point to this directory by entering
 the following in the web browser's navigation bar:
 
    *file:///<path-to>/METplus/docs/_build/html/index.html*
 
-Where <path-to> is the full file path leading to the METplus
-source code. This will direct to the home page of the
-documentation.  Click on the "User's Guide"
-link (which opens the user documentation and the use cases)
-or the "Contributor's Guide" link (which is relevant if the user intends to
-contribute code and/or new use cases).
-
+Where <path-to> is the full file path leading to the METplus source code. This
+will direct to the home page of the documentation.  Click on the links to
+navigate to the desired information.
 
 Relevant Documentation for Contributors
 _______________________________________
 
 The Doxygen tool is employed to create documentation from the source code.
-This documentation
-is useful in generating details about the METplus wrapper API
-(Application Programming Interface).
+This documentation is useful in generating details about the METplus wrapper
+API (Application Programming Interface).
 This is a useful reference for contributors to peruse prior to creating
 new METplus wrappers.
 The Doxygen files located in the */path/to/METplus/docs/doxygen* directory

docs/Release_Guide/met_bugfix.rst

@@ -15,4 +15,3 @@ Create a new vX.Y.Z bugfix release from the main_vX.Y branch.
 .. include:: release_steps/met/attach_release_tarfile.rst
 .. include:: release_steps/met/update_dtc_website.rst
 .. include:: release_steps/finalize_release_on_github_bugfix.rst
-.. include:: release_steps/met/update_docs.rst

docs/Release_Guide/met_development.rst

@@ -15,4 +15,3 @@ Create a new vX.Y.Z-betaN or vX.Y.Z-rcN development release from the develop bra
 .. include:: release_steps/met/attach_release_tarfile.rst
 .. include:: release_steps/met/update_dtc_website.rst
 .. include:: release_steps/finalize_release_on_github_development.rst
-.. include:: release_steps/met/update_docs.rst

docs/Release_Guide/met_official.rst

@@ -16,5 +16,5 @@ Create a new vX.Y.Z official release from the develop branch.
 .. include:: release_steps/met/attach_release_tarfile.rst
 .. include:: release_steps/met/update_dtc_website.rst
 .. include:: release_steps/finalize_release_on_github_official.rst
-.. include:: release_steps/met/update_docs.rst
+.. include:: release_steps/update_docs_official.rst
 

docs/Release_Guide/metcalcpy_bugfix.rst

@@ -10,7 +10,6 @@ Create a new vX.Y.Z bugfix release from the main_vX.Y branch.
 .. include:: release_steps/checkout_main_branch.rst
 .. include:: release_steps/metcalcpy/update_version_bugfix.rst
 .. include:: release_steps/update_release_notes_bugfix.rst
-.. include:: release_steps/metcalcpy/update_docs_bugfix.rst
 .. include:: release_steps/merge_release_issue.rst
 .. include:: release_steps/create_release_on_github.rst
 .. include:: release_steps/metcalcpy/create_release_extra.rst

docs/Release_Guide/metcalcpy_development.rst

@@ -9,7 +9,6 @@ Create a new vX.Y.Z-betaN or vX.Y.Z-rcN development release from the develop bra
 .. include:: release_steps/clone_project_repository.rst
 .. include:: release_steps/checkout_develop_branch.rst
 .. include:: release_steps/metcalcpy/update_version.rst
-.. include:: release_steps/metcalcpy/update_docs_develop.rst
 .. include:: release_steps/merge_release_issue.rst
 .. include:: release_steps/update_release_notes_development.rst
 .. include:: release_steps/create_release_on_github.rst

docs/Release_Guide/metcalcpy_official.rst

@@ -10,12 +10,11 @@ Create a new vX.Y.Z official release from the develop branch.
 .. include:: release_steps/checkout_develop_branch.rst
 .. include:: release_steps/metcalcpy/update_version_official.rst
 .. include:: release_steps/update_release_notes_official.rst
-.. include:: release_steps/metcalcpy/update_docs_tagged.rst
 .. include:: release_steps/merge_release_issue.rst
 .. include:: release_steps/create_release_branch.rst
 .. include:: release_steps/push_release_branch.rst
 .. include:: release_steps/create_release_on_github.rst
 .. include:: release_steps/metcalcpy/create_release_extra.rst
 .. include:: release_steps/finalize_release_on_github_official.rst
 .. include:: release_steps/metcalcpy/update_version_on_develop.rst
-
+.. include:: release_steps/update_docs_official.rst

docs/Release_Guide/metplotpy_bugfix.rst

@@ -5,12 +5,10 @@ METplotpy Bugfix Release
 
 Create a new vX.Y.Z bugfix release from the main_vX.Y branch.
 
-.. include:: release_steps/metcalcpy/update_docs_tagged.rst
 .. include:: release_steps/clone_project_repository.rst
 .. include:: release_steps/checkout_main_branch.rst
 .. include:: release_steps/metplotpy/update_version_bugfix.rst
 .. include:: release_steps/update_release_notes_bugfix.rst
-.. include:: release_steps/metplotpy/update_docs_bugfix.rst
 .. include:: release_steps/merge_release_issue.rst
 .. include:: release_steps/create_release_on_github.rst
 .. include:: release_steps/metplotpy/create_release_extra.rst

docs/Release_Guide/metplotpy_development.rst

@@ -9,7 +9,6 @@ Create a new vX.Y.Z-betaN or vX.Y.Z-rcN development release from the develop bra
 .. include:: release_steps/clone_project_repository.rst
 .. include:: release_steps/checkout_develop_branch.rst
 .. include:: release_steps/metplotpy/update_version.rst
-.. include:: release_steps/metplotpy/update_docs_develop.rst
 .. include:: release_steps/merge_release_issue.rst
 .. include:: release_steps/update_release_notes_development.rst
 .. include:: release_steps/create_release_on_github.rst

docs/Release_Guide/metplotpy_official.rst

@@ -10,11 +10,11 @@ Create a new vX.Y.Z official release from the develop branch.
 .. include:: release_steps/checkout_develop_branch.rst
 .. include:: release_steps/metplotpy/update_version_official.rst
 .. include:: release_steps/update_release_notes_official.rst
-.. include:: release_steps/metplotpy/update_docs_tagged.rst
 .. include:: release_steps/merge_release_issue.rst
 .. include:: release_steps/create_release_branch.rst
 .. include:: release_steps/push_release_branch.rst
 .. include:: release_steps/create_release_on_github.rst
 .. include:: release_steps/metplotpy/create_release_extra.rst
 .. include:: release_steps/finalize_release_on_github_official.rst
 .. include:: release_steps/metplotpy/update_version_official.rst
+.. include:: release_steps/update_docs_official.rst

docs/Release_Guide/metplus_bugfix.rst

@@ -10,7 +10,6 @@ Create a new vX.Y.Z bugfix release from the main_vX.Y branch.
 .. include:: release_steps/checkout_main_branch.rst
 .. include:: release_steps/metplus/update_version_bugfix.rst
 .. include:: release_steps/update_release_notes_bugfix.rst
-.. include:: release_steps/metplus/update_docs_bugfix.rst
 .. include:: release_steps/merge_release_issue.rst
 .. include:: release_steps/create_release_on_github.rst
 .. include:: release_steps/metplus/create_release_extra.rst

docs/Release_Guide/metplus_development.rst

@@ -10,7 +10,6 @@ Create a new vX.Y.Z-betaN or vX.Y.Z-rcN development release from the develop bra
 .. include:: release_steps/checkout_develop_branch.rst
 .. include:: release_steps/metplus/update_version.rst
 .. include:: release_steps/update_release_notes_development.rst
-.. include:: release_steps/metplus/update_docs_develop.rst
 .. include:: release_steps/merge_release_issue.rst
 .. include:: release_steps/create_release_on_github.rst
 .. include:: release_steps/metplus/create_release_extra.rst

docs/Release_Guide/metplus_official.rst

@@ -10,7 +10,6 @@ Create a new vX.Y.Z official release from the develop branch.
 .. include:: release_steps/checkout_develop_branch.rst
 .. include:: release_steps/metplus/update_version_official.rst
 .. include:: release_steps/update_release_notes_official.rst
-.. include:: release_steps/metplus/update_docs_tagged.rst
 .. include:: release_steps/merge_release_issue.rst
 .. include:: release_steps/create_release_branch.rst
 .. include:: release_steps/metplus/update_readme.rst
@@ -20,3 +19,4 @@ Create a new vX.Y.Z official release from the develop branch.
 .. include:: release_steps/metplus/update_dtc_website.rst
 .. include:: release_steps/finalize_release_on_github_official.rst	     
 .. include:: release_steps/metplus/update_version_on_develop.rst
+.. include:: release_steps/update_docs_official.rst