Deploy documentation to RTD (#1264)

Adds an Github action that will build and deploy documentation as artifacts for with every push to develop.
The artifacts can be downloaded from Actions -> Documentation -> Artifacts

Refs: #9

.github/scripts/build_docs.sh

@@ -0,0 +1,31 @@
+#! /bin/bash
+
+set -eux
+
+# path to docs directory relative to top level of repository
+# $GITHUB_WORKSPACE is set if the actions/checkout@v3 action is run first
+
+cwd=$(pwd)
+DOCS_DIR="${GITHUB_WORKSPACE}/docs"
+
+# run Make to build the documentation and return to previous directory
+cd "${DOCS_DIR}"
+make clean html
+cd "${cwd}"
+
+# copy HTML output into directory to create an artifact
+mkdir -p artifact/documentation
+cp -R "${DOCS_DIR}/build/html/." artifact/documentation
+
+# check if the warnings.log file is empty
+# Copy it into the artifact and documeentation directories
+# so it will be available in the artifacts
+warning_file="${DOCS_DIR}/build/warnings.log"
+if [[ -s ${warning_file} ]]; then
+  cp -r "${DOCS_DIR}/build/warnings.log" artifact/doc_warnings.log
+  cp artifact/doc_warnings.log artifact/documentation
+  echo "Warnings were encountered while building documentation."
+  echo "========== Begin warnings =========="
+  cat artifact/doc_warnings.log
+  echo "=========== End warnings ==========="
+fi

.github/workflows/docs.yaml

@@ -0,0 +1,51 @@
+name: Build and Deploy Documentation
+on:
+  push:
+    branches:
+      - develop
+      - feature/*
+      - main/*
+      - bugfix/*
+      - release/*
+    paths:
+      - docs/**
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+jobs:
+  documentation:
+    runs-on: ubuntu-latest
+    name: Build and deploy documentation
+
+    steps:
+    - name: Setup Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.9"
+
+    - name: Install (upgrade) python dependencies
+      run: |
+        pip install --upgrade pip sphinx sphinx-gallery sphinx_rtd_theme sphinxcontrib-bibtex
+
+    - name: Checkout
+      uses: actions/checkout@v3
+
+    - name: Build documentation
+      run: |
+        ./.github/scripts/build_docs.sh
+
+    - name: Upload documentation (on success)
+      uses: actions/upload-artifact@v3
+      if: always()
+      with:
+        name: documentation
+        path: artifact/documentation
+
+    - name: Upload warnings (on failure)
+      uses: actions/upload-artifact@v3
+      if: failure()
+      with:
+        name: documentation_warnings.log
+        path: artifact/doc_warnings.log
+        if-no-files-found: ignore
+

README.md

@@ -1,5 +1,5 @@
 # global-workflow
-Global Superstructure/Workflow currently supporting the Finite-Volume on a Cubed-Sphere Global Forecast System (FV3GFS)
+Global Workflow currently supporting the Global Forecast System (GFS) with the UFS-weather-model and GSI-based Data Assimilation System.
 
 The global-workflow depends on the following prerequisities to be available on the system:
 
@@ -11,45 +11,10 @@ The global-workflow current supports the following tier-1 machines:
 
 * Hera
 * Orion
+* WCOSS2 - NOAA's operational HPC
 
 Additionally, the following tier-2 machine is supported:
 * S4 (Note that S2S+ experiments are not fully supported)
 
-Quick-start instructions are below. Full instructions are available in the [wiki](https://github.com/NOAA-EMC/global-workflow/wiki/Run-Global-Workflow)
+Documentation (in progress) is available [here](https://global-workflow.readthedocs.io/en/latest/)
 
-## Build global-workflow:
-
-### 1. Check out components
-
-While in /sorc folder:
-```
-$ sh checkout.sh
-```
-
-### 2. Build components
-
-While in /sorc folder:
-
-```
-$ sh build_all.sh
-```
-
-Or use an available option:  
-```
-build_all.sh [-a UFS_app][-c build_config][-h][-v]
-  -a UFS_app:
-    Build a specific UFS app instead of the default
-  -c build_config:
-    Selectively build based on the provided config instead of the default config
-  -h:
-    Print usage message and exit
-  -v:
-    Run all scripts in verbose mode
-```
-
-### 3. Link components
-
-While in /sorc folder:
-
-$ sh link_workflow.sh emc $MACHINE
-...where $MACHINE is "dell", "cray", "hera", or "orion".

docs/Makefile

@@ -12,9 +12,14 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+# Sphinx doesn't know to clean out the debris from sphinx-gallery
+clean:
+	rm -rf $(BUILDDIR)/*
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	[ -d $(BUILDDIR) ] || mkdir -p $(BUILDDIR)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -w "$(BUILDDIR)/warnings.log"