From be863bc9aad861d024ed528dd3c8509ee6a4c2b8 Mon Sep 17 00:00:00 2001 From: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com> Date: Tue, 12 Nov 2024 12:53:44 -0500 Subject: [PATCH] [develop]: Add GitHub Actions to check that Technical Docs are up-to-date (#1152) * Adds a GitHub Actions workflow & 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. --- .github/scripts/check_tech_doc.sh | 28 ++++++++++ .github/workflows/doc_tests.yaml | 25 +++++++++ doc/ContribGuide/documentation.rst | 52 ++++++++++++++++++- doc/Makefile | 2 +- ...eds.rst => set_fv3nml_ens_stoch_seeds.rst} | 0 ...rst => set_fv3nml_sfc_climo_filenames.rst} | 0 .../BuildingRunningTesting/VXCases.rst | 3 +- .../CustomizingTheWorkflow/DefineWorkflow.rst | 2 +- doc/conf.py | 10 +--- doc/requirements.in | 3 +- doc/requirements.txt | 9 +--- 11 files changed, 112 insertions(+), 22 deletions(-) create mode 100755 .github/scripts/check_tech_doc.sh create mode 100644 .github/workflows/doc_tests.yaml rename doc/TechDocs/ush/{set_FV3nml_ens_stoch_seeds.rst => set_fv3nml_ens_stoch_seeds.rst} (100%) rename doc/TechDocs/ush/{set_FV3nml_sfc_climo_filenames.rst => set_fv3nml_sfc_climo_filenames.rst} (100%) diff --git a/.github/scripts/check_tech_doc.sh b/.github/scripts/check_tech_doc.sh new file mode 100755 index 0000000000..d988e50cd6 --- /dev/null +++ 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 new file mode 100644 index 0000000000..34fb01a9ac --- /dev/null +++ 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 index 9e0bad6bda..babcd24368 100644 --- 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 \ No newline at end of file + 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 index c91f2f147b..9663ba3996 100644 --- 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 similarity index 100% rename from doc/TechDocs/ush/set_FV3nml_ens_stoch_seeds.rst rename to 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 similarity index 100% rename from doc/TechDocs/ush/set_FV3nml_sfc_climo_filenames.rst rename to doc/TechDocs/ush/set_fv3nml_sfc_climo_filenames.rst diff --git a/doc/UsersGuide/BuildingRunningTesting/VXCases.rst b/doc/UsersGuide/BuildingRunningTesting/VXCases.rst index b36afcefd4..f8b01f993c 100644 --- 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 ` 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 `_ and `MBIAS `_ 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 `. +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 `_) and Magnitude & +Multiplicative bias (`MBIAS `_) 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 `. 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 index 4ea8f7052d..b5d587969e 100644 --- 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 `__) and structured YAML files. The YAML follows the requirements in the `Rocoto documentation `__ 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 `_) and structured YAML files. The YAML follows the requirements in the `Rocoto documentation `__ with a few exceptions or additions outlined in this documentation. The Jinja2 Template =================== diff --git a/doc/conf.py b/doc/conf.py index f1f094d545..5989ae0d74 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -38,7 +38,7 @@ nitpick_ignore = [('py:class', 'obj'),('py:class', 'yaml.dumper.Dumper'),('py:class', - 'xml.etree.ElementTree'),] + 'xml.etree.ElementTree'),('py:class', 'Basemap'),] # -- General configuration --------------------------------------------------- @@ -46,7 +46,6 @@ 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 \ No newline at end of file diff --git a/doc/requirements.in b/doc/requirements.in index 831cdc431d..75a70ab416 100644 --- 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 index 38fdd2ef01..faa8455abe 100644 --- 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