test docs on CI

.github/workflows/test-docs.yml

@@ -0,0 +1,60 @@
+name: Test docs
+
+# The tests defined in docs/ are currently influenced by changes to _version.py
+# and scopes.py.
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "zmq/**"
+      - ".github/workflows/test-docs.yml"
+  push:
+    paths:
+      - "docs/**"
+      - "zmq/**"
+      - ".github/workflows/test-docs.yml"
+    branches-ignore:
+      - "dependabot/**"
+      - "pre-commit-ci-update-config"
+    tags:
+      - "**"
+  workflow_dispatch:
+
+env:
+  LANG: C.UTF-8
+  SPHINXOPTS: "-W"
+
+jobs:
+  test-docs:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install libzmq
+        run: |
+          sudo apt-get -y install libzmq3-dev
+
+      - name: Install pyzmq
+        run: |
+          pip install -v .
+
+      - name: Install requirements
+        run: |
+          pip install -r docs/requirements.txt
+
+      # readthedocs doesn't halt on warnings,
+      # so raise any warnings here
+      - name: build docs
+        run: |
+          cd docs
+          make html
+
+      - name: check links
+        run: |
+          cd docs
+          make linkcheck

.github/workflows/test.yml

@@ -8,12 +8,14 @@ on:
     paths-ignore:
       - "docs/**"
       - "tools/**"
-      - .github/workflows/wheels.yml
+      - ".github/workflows/*"
+      - "!.github/workflows/test.yml"
   pull_request:
     paths-ignore:
       - "docs/**"
       - "tools/**"
-      - .github/workflows/wheels.yml
+      - ".github/workflows/*"
+      - "!.github/workflows/test.yml"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

docs/Makefile

@@ -2,16 +2,16 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -n
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = build
-SRCDIR        = source
+SPHINXOPTS    ?= -n
+SPHINXBUILD   ?= sphinx-build
+PAPER         ?=
+BUILDDIR      ?= build
+SRCDIR        ?= source
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -n -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
 
 .PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest