From 95b2bf7a50826068b666659162051f69af9e3d06 Mon Sep 17 00:00:00 2001
From: Jean-Christophe Morin <jean_christophe_morin@hotmail.com>
Date: Fri, 17 Nov 2023 21:15:14 -0500
Subject: [PATCH] Add docs workflow

Signed-off-by: Jean-Christophe Morin <jean_christophe_morin@hotmail.com>
---
 .github/workflows/ci.yaml   |   8 +--
 .github/workflows/docs.yaml | 111 ++++++++++++++++++++++++++++++++++++
 docs/Makefile               |  10 +++-
 3 files changed, 123 insertions(+), 6 deletions(-)
 create mode 100644 .github/workflows/docs.yaml

diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index b3ee9ae..bd40f03 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -5,14 +5,14 @@ on:
   push:
     paths-ignore:
     - .github/workflows/update_pip.yaml
-    - docs/**
-    - .readthedocs.yaml
+    - '**/docs/**'
+    - '**/.readthedocs.yaml'
     - '**/*.md'
   pull_request:
     paths-ignore:
     - .github/workflows/update_pip.yaml
-    - docs/**
-    - .readthedocs.yaml
+    - '**/docs/**'
+    - '**/.readthedocs.yaml'
     - '**/*.md'
 
 concurrency:
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
new file mode 100644
index 0000000..866a9ae
--- /dev/null
+++ b/.github/workflows/docs.yaml
@@ -0,0 +1,111 @@
+name: docs
+
+on:
+  push:
+    paths:
+    - '**/CHANGELOG.md'
+    - 'docs/**'
+    - '.github/workflows/docs.yaml'
+  pull_request:
+    paths:
+    - '**/CHANGELOG.md'
+    - 'docs/**'
+    - '.github/workflows/docs.yaml'
+
+jobs:
+  check-links:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        submodules: 'recursive'
+
+    - uses: actions/setup-python@v4.3.0
+      with:
+        python-version: '3.11'
+
+    - name: Create virtualenv
+      run: python3 -m venv .venv
+
+    - name: Install dependencies
+      run: |
+        source .venv/bin/activate
+        python -m pip install .
+        python -m pip install -r docs/requirements.txt
+
+    - name: Linkcheck
+      working-directory: docs
+      run: |
+        source ../.venv/bin/activate
+
+        set +e
+        make linkcheck
+        exit_code=$?
+
+        set -e
+
+        if [ $exit_code -eq 0 ]; then
+            echo -e "\n\n=================\nAll links are valid!"
+
+            echo "# :heavy_check_mark: Sphinx links" >> $GITHUB_STEP_SUMMARY
+            echo "All links are valid!" >> $GITHUB_STEP_SUMMARY
+        else
+            echo -e "\n\n=================\nFound broken links. Look at the build logs.\n"
+
+            echo "# :x: Sphinx links" >> $GITHUB_STEP_SUMMARY
+            echo "Found broken links. Look at the build logs for additional information." >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            cat build/linkcheck/output.txt >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+        fi
+
+        exit $exit_code
+
+  check-warnings:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        submodules: 'recursive'
+
+    - uses: actions/setup-python@v4.3.0
+      with:
+        python-version: '3.11'
+
+    - name: Create virtualenv
+      run: python3 -m venv .venv
+
+    - name: Install dependencies
+      run: |
+        source .venv/bin/activate
+        python -m pip install .
+        python -m pip install -r docs/requirements.txt
+
+    - name: Check warnings/errors
+      working-directory: docs
+      run: |
+        source ../.venv/bin/activate
+
+        set +e
+        make htmlstrict
+
+        exit_code=$?
+
+        set -e
+
+        if [ $exit_code -eq 0 ]; then
+            echo -e "\n\n=================\nNo warnings or errors detected!"
+            echo "# :heavy_check_mark: Sphinx warnings/errors" >> $GITHUB_STEP_SUMMARY
+            echo "No errors or warnings detected!" >> $GITHUB_STEP_SUMMARY
+        else
+            echo -e "\n\n=================\nWarnings and or errors detected; See the summary bellow:\n"
+            cat _build/htmlstrict/output.txt
+
+            echo "# :x: Sphinx warnings/errors" >> $GITHUB_STEP_SUMMARY
+            echo "Found some warnings or errors:" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            cat _build/htmlstrict/output.txt >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+        fi
+
+        exit $exit_code
diff --git a/docs/Makefile b/docs/Makefile
index 796112f..92507f1 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -12,7 +12,7 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile htmlstrict
 
 livehtml:
 	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@@ -20,4 +20,10 @@ livehtml:
 # 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)
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: htmlstrict
+htmlstrict:
+	$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" -W --keep-going -w $(BUILDDIR)/htmlstrict/output.txt
+	@echo
+	@echo "Warnings check complete."