From 6713eaeb829df2cffbc0c959d17b1f14033d783c Mon Sep 17 00:00:00 2001 From: Rahul Mahajan Date: Mon, 23 Jan 2023 09:32:31 -0500 Subject: [PATCH] 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 | 31 +++++++++++++++++++++ .github/workflows/docs.yaml | 51 +++++++++++++++++++++++++++++++++++ README.md | 41 +++------------------------- docs/Makefile | 7 ++++- 4 files changed, 91 insertions(+), 39 deletions(-) create mode 100755 .github/scripts/build_docs.sh create mode 100644 .github/workflows/docs.yaml diff --git a/.github/scripts/build_docs.sh b/.github/scripts/build_docs.sh new file mode 100755 index 0000000000..7fb6701da2 --- /dev/null +++ b/.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 diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000000..ae083a3c0b --- /dev/null +++ b/.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 + diff --git a/README.md b/README.md index 750666e517..5620112f3c 100644 --- a/README.md +++ b/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". diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf102..72173f32a7 100644 --- a/docs/Makefile +++ b/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"