From a65c1b28bc766407b15ce88284351f2226948874 Mon Sep 17 00:00:00 2001
From: Victor Lin <13424970+victorlin@users.noreply.github.com>
Date: Tue, 3 May 2022 09:52:36 -0700
Subject: [PATCH] Workflows for Sphinx docs CI

This parallels the motivation behind 6245d9e4d031a244d32979e4a27c6badcb503854 for pathogen repo CI, but for repos containing Sphinx documentation.

As a starting point, the reusable workflow fails on build warnings such as invalid links and bad formatting.
---
 .github/workflows/docs-ci.yaml             | 47 ++++++++++++++++++++++
 workflow-templates/docs-ci.properties.json |  4 ++
 workflow-templates/docs-ci.yaml            |  9 +++++
 workflow-templates/pathogen-repo-ci.yaml   |  3 ++
 4 files changed, 63 insertions(+)
 create mode 100644 .github/workflows/docs-ci.yaml
 create mode 100644 workflow-templates/docs-ci.properties.json
 create mode 100644 workflow-templates/docs-ci.yaml

diff --git a/.github/workflows/docs-ci.yaml b/.github/workflows/docs-ci.yaml
new file mode 100644
index 0000000..70e9ebb
--- /dev/null
+++ b/.github/workflows/docs-ci.yaml
@@ -0,0 +1,47 @@
+# This workflow is intended to be called by workflows in our various software
+# repos containing Sphinx documentation projects.
+# See workflow-templates/docs-ci.yaml (a "starter" workflow) in this repo for
+# an example of what the caller workflow looks like.
+name: Sphinx docs CI
+
+on:
+  workflow_call:
+    inputs:
+      docs-directory:
+        description: >-
+          Directory containing Makefile. (e.g. docs/)
+        type: string
+        required: true
+
+      environment-file:
+        description: >-
+          Path to conda environment file (e.g. docs/conda.yml)
+        type: string
+        required: true
+
+      make-target:
+        description: >-
+          Sphinx builder name. See https://www.sphinx-doc.org/en/master/man/sphinx-build.html#options
+        type: string
+        default: html
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+    - uses: actions/checkout@v3
+    - uses: conda-incubator/setup-miniconda@v2
+      with:
+        environment-file: ${{ inputs.environment-file }}
+    - run: conda list
+    - run: make ${{ inputs.make-target }}
+      working-directory: ${{ inputs.docs-directory }}
+      env:
+        # https://www.sphinx-doc.org/en/master/man/sphinx-build.html
+        # -n: warn on missing references
+        # -W: error on warnings
+        # --keep-going: find all warnings
+        SPHINXOPTS: -n -W --keep-going
diff --git a/workflow-templates/docs-ci.properties.json b/workflow-templates/docs-ci.properties.json
new file mode 100644
index 0000000..da4074c
--- /dev/null
+++ b/workflow-templates/docs-ci.properties.json
@@ -0,0 +1,4 @@
+{
+  "name": "CI for Sphinx docs",
+  "description": "Basic CI workflow for repos containing a Sphinx documentation project"
+}
diff --git a/workflow-templates/docs-ci.yaml b/workflow-templates/docs-ci.yaml
new file mode 100644
index 0000000..f813cea
--- /dev/null
+++ b/workflow-templates/docs-ci.yaml
@@ -0,0 +1,9 @@
+name: Sphinx docs CI
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  ci:
+    uses: nextstrain/.github/.github/workflows/docs-ci.yaml@master
diff --git a/workflow-templates/pathogen-repo-ci.yaml b/workflow-templates/pathogen-repo-ci.yaml
index b1f5bca..d63da24 100644
--- a/workflow-templates/pathogen-repo-ci.yaml
+++ b/workflow-templates/pathogen-repo-ci.yaml
@@ -7,3 +7,6 @@ on:
 jobs:
   ci:
     uses: nextstrain/.github/.github/workflows/pathogen-repo-ci.yaml@master
+    with:
+      docs-directory: docs/
+      environment-file: docs/conda.yml