Deploy documentation to RTD

.github/scripts/build_docs.sh

@@ -0,0 +1,26 @@
+#! /bin/bash
+
+# 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}" || ( echo "unable to cd into ${DOCS_DIR}, ABORT!"; exit 1 )
+make clean html
+cd "${cwd}" || ( echo "unable to cd into ${cwd}, ABORT!"; exit 1 )
+
+# 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,54 @@
+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
+
+    - name: Checkout
+      uses: actions/checkout@v3
+      with:
+        path: global-workflow
+
+    - name: Build documentation
+      run: |
+        cd ${GITHUB_WORKSPACE}/global-workflow
+        ./.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
+