Configure sphinx warnings as errors (#7697)

Author: graingert

.readthedocs.yaml

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

distributed/scheduler.py

@@ -616,7 +616,7 @@ def memory(self) -> MemoryState:
            goes back down, and spilled goes down by 100MB as it should have to
            begin with.
 
-        https://github.com/dask/distributed/issues/6002 will let us solve this.
+        :issue:`6002` will let us solve this.
         """
         return MemoryState(
             process=self.metrics["memory"],

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -j4
+SPHINXOPTS    = -j4 -W --keep-going
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build

docs/source/changelog.rst

@@ -1125,7 +1125,7 @@ Released on May 2, 2022
 
 Highlights
 ^^^^^^^^^^
-This is a bugfix release for `this issue <https://github.com/dask/distributed/issues/6255>`_.
+This is a bugfix release for :issue:`this issue<6255>`.
 
 Enhancements
 ^^^^^^^^^^^^

docs/source/conf.py

@@ -426,6 +426,12 @@
 </html>
 """
 
+suppress_warnings = [
+    # more than one target found for cross-reference
+    # https://github.com/sphinx-doc/sphinx/issues/10400
+    "ref.python"
+]
+
 
 def copy_legacy_redirects(app, docname):
     if app.builder.name == "html":

docs/source/killed.rst

@@ -86,8 +86,7 @@ as you would for ordinary exceptions happening during task execution.
 Specifically for connectivity problems (e.g., timeout exceptions in the worker
 logs), you will need to diagnose your networking infrastructure, which is more
 complicated than can be described here. Commonly, it may involve logging into
-the machine running the affected worker
-(although you can :ref:`ipylaunch`).
+the machine running the affected worker.
 
 Killed by Nanny
 '''''''''''''''

docs/source/queues.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 Data Streams with Queues
 ========================
 

docs/source/worker-state.rst

@@ -1,4 +1,5 @@
 .. _worker-state:
+
 Worker State Machine
 ====================