Add docs workflow (#69)

Signed-off-by: Jean-Christophe Morin <jean_christophe_morin@hotmail.com>

.github/workflows/ci.yaml

@@ -5,13 +5,13 @@ 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/**
+    - 'docs/**'
     - .readthedocs.yaml
     - '**/*.md'
 

.github/workflows/docs.yaml

@@ -0,0 +1,106 @@
+name: docs
+
+on:
+  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

docs/Makefile

@@ -12,12 +12,18 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile htmlstrict
 
 livehtml:
 	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # 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."