[develop]: Add GitHub Actions to check that Technical Docs are up-to-date (#1152)

gspetro-NOAA · web-flow · commit be863bc9aad8 · 2024-11-12T12:53:44.000-05:00
* Adds a GitHub Actions workflow &amp; script to check whether the Technical Documentation is up-to-date
* Turns on the -W flag so that documentation build warnings register as error
* Updates the requirements file so that --remove-old flag can be used to check Tech Docs
* Updates the Contributor's Guide w/information on Technical Documentation and troubleshooting guidelines
* Fixes a few broken links.
diff --git a/.github/scripts/check_tech_doc.sh b/.github/scripts/check_tech_doc.sh
@@ -0,0 +1,28 @@
+#!/bin/bash
+# This script recreates technical documentation for the ush and tests/WE2E Python scripts
+# If the tech docs produced here do not match the branch's contents, the script will fail
+
+set -eo pipefail
+
+# Install prerequisites
+pip install sphinx
+pip install sphinx-rtd-theme
+pip install sphinxcontrib-bibtex
+
+# Regenerate tech docs in ush and tests/WE2E based on current state of scripts in those directories.
+cd doc/TechDocs
+sphinx-apidoc -fM --remove-old -o ./ush ../../ush
+sphinx-apidoc -fM --remove-old -o ./tests/WE2E ../../tests/WE2E
+
+# Check for mismatch between what comes out of this action and what is in the PR. 
+status=`git status -s`
+
+if [ -n "${status}" ]; then
+  echo ${status}
+  echo ""
+  echo "Please update your Technical Documentation RST files."
+  exit 1
+else
+  echo "Technical documentation is up-to-date."
+  exit 0
+fi
diff --git a/.github/workflows/doc_tests.yaml b/.github/workflows/doc_tests.yaml
@@ -0,0 +1,25 @@
+name: Doc Tests
+on:
+  push:
+  pull_request:
+    branches:
+      - develop
+      - 'release/*'
+  workflow_dispatch:
+
+defaults:
+  run:
+    shell: bash -leo pipefail {0}
+
+jobs:
+  doc_tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Check tech docs
+        run: .github/scripts/check_tech_doc.sh
+      - name: Build documentation
+        run: |
+          cd doc
+          make doc
diff --git a/doc/ContribGuide/documentation.rst b/doc/ContribGuide/documentation.rst
@@ -69,4 +69,54 @@ Please follow these guidelines when contributing to the documentation:
 
         .. code-block:: python
 
-           n = 88
+           n = 88
+
+Troubleshooting Documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the SRW App documentation Makefile (``ufs-srweather-app/doc/Makefile``), the ``-W`` option causes documentation builds to fail when there are errors or warnings in the build. 
+This ensures that the documentation remains up-to-date and notifies developers of any new issues (like failing links). However, the build will fail when it hits the first error without showing subsequent errors. 
+When troubleshooting, it can be useful to see all warnings and errors. 
+To see all warnings and errors, comment out the ``-W`` flag in ``SPHINXOPTS`` in the Makefile and build the documentation by running ``make doc`` from the ``doc`` directory. 
+
+Technical Documentation Guidelines
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Technical (API-like) documentation is generated for any Python scripts in the ``ush`` or ``tests/WE2E`` directories. 
+When developers change Python files in these directories, they need to update the Python docstrings (i.e., comments in ``"""triple quotes"""``) to reflect the changes they made. 
+Each Python script should include: 
+
+   * A summary of the script's purpose/functionality
+      
+      * Should start with a verb, e.g., "checks" or "loads" or "initializes"
+
+   * Docstrings for each method (except methods like ``_parse_args`` that start with an underscore). These docstrings should include:
+
+      * A description of what the method does (starting with a verb, e.g., "checks" or "parses")
+      * A list of method parameters, or ``Args:``, with a definition and expected data type for each
+      * A return statement (``Returns:``) -- if applicable
+      * List of exceptions (``Raises:``) -- if applicable
+
+.. note:: 
+   
+   Python does not have truly private methods, but methods that start with an underscore are the closest equivalent. In the SRW App, the underscore signals that this method is only accessed by the script within which it is called. 
+
+After updating the docstrings, developers need to update the corresponding RST files. 
+To do this successfully, developers must have *sphinx>=7.4.0* installed on their system. To update the RST files, run: 
+
+.. code-block:: console
+
+   cd ufs-srweather-app/doc/TechDoc
+   sphinx-apidoc -fM --remove-old -o ./ush ../../ush
+   sphinx-apidoc -fM --remove-old -o ./tests/WE2E ../../tests/WE2E
+
+.. note:: 
+
+   Developers who do not have *sphinx>=7.4.0* installed may issue the following commands from ``ufs-srweather-app/doc/TechDoc`` before running the sphinx-apidoc commands above: 
+
+   .. code-block:: console
+
+      rm -rf ush
+      rm -rf tests/WE2E
+   
+   This will delete current RST files before recreating them with the ``sphinx-apidoc`` command based on the current contents of ``ush`` and ``tests/WE2E``. This step is necessary because the ``--remove-old`` flag does not work with earlier versions of sphinx. 
diff --git a/doc/Makefile b/doc/Makefile
@@ -1,6 +1,6 @@
 # Makefile for Sphinx documentation
 
-SPHINXOPTS    = -a -n #-W
+SPHINXOPTS    = -a -n -W
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = build
diff --git a/doc/TechDocs/ush/set_fv3nml_ens_stoch_seeds.rst b/doc/TechDocs/ush/set_fv3nml_ens_stoch_seeds.rst
diff --git a/doc/TechDocs/ush/set_fv3nml_sfc_climo_filenames.rst b/doc/TechDocs/ush/set_fv3nml_sfc_climo_filenames.rst
diff --git a/doc/UsersGuide/BuildingRunningTesting/VXCases.rst b/doc/UsersGuide/BuildingRunningTesting/VXCases.rst
@@ -262,7 +262,8 @@ Point STAT Files
 
 The Point-Stat files contain continuous variables like temperature, pressure, and wind speed. A description of the Point-Stat file can be found :ref:`here <met:point-stat>` in the MET documentation. 
 
-The Point-Stat files contain a potentially overwhelming amount of information. Therefore, it is recommended that users focus on the CNT MET test, which contains the `RMSE <https://metplus.readthedocs.io/projects/met/en/latest/Users_Guide/appendixC.html#root-mean-squared-error-rmse>`_ and `MBIAS <https://metplus.readthedocs.io/projects/met/en/latest/Users_Guide/appendixC.html#multiplicative-bias>`_ statistics. The MET tests are defined in column 24 'LINE_TYPE' of the ``.stat`` file. Look for 'CNT' in this column. Then find column 66-68 for MBIAS and 78-80 for RMSE statistics. A full description of this file can be found :ref:`here <met:point_stat-output>`.
+The Point-Stat files contain a potentially overwhelming amount of information. Therefore, it is recommended that users focus on the CNT MET test, which contains the Root Mean Squared Error (`RMSE <https://metplus.readthedocs.io/en/latest/Users_Guide/statistics_list.html#statistics-list-p-r>`_) and Magnitude &
+Multiplicative bias (`MBIAS <https://metplus.readthedocs.io/en/latest/Users_Guide/statistics_list.html#statistics-list-g-m>`_) statistics. The MET tests are defined in column 24 'LINE_TYPE' of the ``.stat`` file. Look for 'CNT' in this column. Then find column 66-68 for MBIAS and 78-80 for RMSE statistics. A full description of this file can be found :ref:`here <met:point_stat-output>`.
 
 To narrow down the variable field even further, users can focus on these weather variables: 
 
diff --git a/doc/UsersGuide/CustomizingTheWorkflow/DefineWorkflow.rst b/doc/UsersGuide/CustomizingTheWorkflow/DefineWorkflow.rst
@@ -6,7 +6,7 @@ Defining an SRW App Workflow
 
 Many predefined workflows with optional variants exist within the Short-Range Weather Application, but the Application also includes the ability to define a new workflow from scratch. This functionality allows users to add tasks to the workflow to meet their scientific exploration needs.
 
-Rocoto is the primary workflow manager software used by the UFS SRW App. Rocoto workflows are defined in an XML file (``FV3LAM_wflow.xml``) based on parameters set during experiment generation. This section explains how the Rocoto XML is built using a Jinja2 template (`Jinja docs here <https://jinja.palletsprojects.com/en/3.1.x/templates/>`__) and structured YAML files. The YAML follows the requirements in the `Rocoto documentation <http://christopherwharrop.github.io/rocoto/>`__ with a few exceptions or additions outlined in this documentation.
+Rocoto is the primary workflow manager software used by the UFS SRW App. Rocoto workflows are defined in an XML file (``FV3LAM_wflow.xml``) based on parameters set during experiment generation. This section explains how the Rocoto XML is built using a Jinja2 template (`Jinja docs here <https://jinja.palletsprojects.com/en/stable/templates>`_) and structured YAML files. The YAML follows the requirements in the `Rocoto documentation <http://christopherwharrop.github.io/rocoto/>`__ with a few exceptions or additions outlined in this documentation.
 
 The Jinja2 Template
 ===================
diff --git a/doc/conf.py b/doc/conf.py
@@ -38,15 +38,14 @@
 
 nitpick_ignore = [('py:class', 'obj'),('py:class', 
                    'yaml.dumper.Dumper'),('py:class', 
-                   'xml.etree.ElementTree'),]
+                   'xml.etree.ElementTree'),('py:class', 'Basemap'),]
 
 # -- General configuration ---------------------------------------------------
 
 # Sphinx extension module names:
 extensions = [
     'sphinx_rtd_theme',
     'sphinx.ext.autodoc',
-    'sphinxcontrib.autoyaml',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
@@ -310,10 +309,3 @@ def warn_undocumented_members(app, what, name, obj, options, lines):
             'uw': ('https://uwtools.readthedocs.io/en/main/%s', '%s'),
             }
 
-# -- Options for autoyaml extension ---------------------------------------
-
-autoyaml_root = "../ush"
-autoyaml_doc_delimiter = "###" # Character(s) which start a documentation comment.
-autoyaml_comment = "#" #Comment start character(s).
-autoyaml_level = 6
-#autoyaml_safe_loader = False
diff --git a/doc/requirements.in b/doc/requirements.in
@@ -1,4 +1,3 @@
-sphinx>=6.0.0
+sphinx>=7.4.0
 sphinx_rtd_theme
 sphinxcontrib-bibtex
-sphinxcontrib-autoyaml
diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -2,7 +2,7 @@
 # This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
-#    pip-compile --strip-extras requirements.in
+#    pip-compile requirements.in
 #
 alabaster==0.7.16
     # via sphinx
@@ -42,27 +42,22 @@ pyyaml==6.0.1
     # via pybtex
 requests==2.32.2
     # via sphinx
-ruamel-yaml==0.16.13
-    # via sphinxcontrib-autoyaml
 six==1.16.0
     # via
     #   latexcodec
     #   pybtex
 snowballstemmer==2.2.0
     # via sphinx
-sphinx==7.2.6
+sphinx==7.4.7
     # via
     #   -r requirements.in
     #   sphinx-rtd-theme
-    #   sphinxcontrib-autoyaml
     #   sphinxcontrib-bibtex
     #   sphinxcontrib-jquery
 sphinx-rtd-theme==2.0.0
     # via -r requirements.in
 sphinxcontrib-applehelp==1.0.8
     # via sphinx
-sphinxcontrib-autoyaml==1.1.1
-    # via -r requirements.in
 sphinxcontrib-bibtex==2.6.2
     # via -r requirements.in
 sphinxcontrib-devhelp==1.0.6
