diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 07156efb..5332bd9a 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -19,6 +19,7 @@ build:
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
     configuration: docs/conf.py
+    fail_on_warning: true
 
 # Optionally build your docs in additional formats such as PDF and ePub
 # formats:
diff --git a/docs/conf.py b/docs/conf.py
index 0eb7d03f..c630b74d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -27,6 +27,7 @@
 
 extensions: list[str] = [
     "sphinx.ext.intersphinx",
+    "sphinx_codeautolink",
 ]
 
 intersphinx_mapping = {
@@ -38,6 +39,11 @@
     # see https://github.com/encode/httpx/discussions/1220
     # we only have a few references to httpx though, so can just link manually.
 }
+
+# these are disabled by default, might re-disable them if they turn out to be noisy
+codeautolink_warn_on_missing_inventory = True
+codeautolink_warn_on_failed_resolve = True
+
 templates_path = ["_templates"]
 exclude_patterns: list[str] = ["_build", "Thumbs.db", ".DS_Store"]
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
index d3a945f2..ba9bd0b1 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1 +1,2 @@
 libcst
+sphinx-codeautolink