doc: fail on warning

We want clean builds without warnings.
Enable fail on warning in the readthedocs pipeline and in local builds.

.readthedocs.yaml

@@ -11,6 +11,7 @@ build:
 
 sphinx:
    configuration: doc/conf.py
+   fail_on_warning: true
 
 python:
    install:

doc/Makefile

@@ -1,5 +1,5 @@
 # These variables can be overridden from the command line from the environment.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -W --keep-going # treat warnings as errors, but process all files when an error occurs
 SOURCEDIR     = .
 BUILDDIR      = _build
 
@@ -16,9 +16,10 @@ html latex latexpdf linkcheck help:
 	sphinx-build -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 
 # Autobuild; automatically build HTML on source changes and serve on localhost
+# Note: most options are forwarded as-is to sphinx, but --keep-going is not understood and we explicitly drop it.
 .PHONY: autobuild
 autobuild:
-	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(filter-out --keep-going,$(SPHINXOPTS))
 
 # Generate commandline docs by building the tools and running their `gendocus` subcommand
 .PHONY: command-gendocs