Deploy documentation to RTD

.github/scripts/build_docs.sh

@@ -0,0 +1,28 @@
+#! /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
+  exit 1
+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:
+  create_documentation:
+    runs-on: ubuntu-latest
+    name: 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
+

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"