diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 000000000..221ca4396
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,34 @@
+version: 2
+
+formats:
+  - htmlzip
+
+# build with latest available ubuntu version
+build:
+  os: ubuntu-lts-latest
+  tools:
+    python: "3.12"
+  # need to install playwright deps via apt (lack of sudo means we can't use
+  # `playwright install-deps`).  NB: Graphviz is a separate dep urelated to playwright
+  apt_packages:
+    - graphviz
+    - libasound2
+    - libdbus-glib-1-2
+  jobs:
+    # build the gallery of themes before building the doc
+    post_install:
+      - pip install playwright
+      - playwright install chromium
+      - python ./docs/scripts/generate_gallery_images.py
+
+sphinx:
+  configuration: docs/conf.py
+  # builder: "dirhtml"
+  fail_on_warning: false # we have some unavoidable warnings, and a separate warnings checker
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - doc
diff --git a/docs/conf.py b/docs/conf.py
index afab8132c..3c59d24fc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -291,6 +291,27 @@
 autoapi_root = "api"
 autoapi_member_order = "groupwise"
 
+# -- Warnings / Nitpicky -------------------------------------------------------
+
+nitpicky = True
+bad_classes = (
+    r".*abc def.*",  # urllib.parse.unquote_to_bytes
+    r"api_sample\.RandomNumberGenerator",
+    r"bs4\.BeautifulSoup",
+    r"docutils\.nodes\.Node",
+    r"matplotlib\.artist\.Artist",  # matplotlib xrefs are in the class diagram demo
+    r"matplotlib\.figure\.Figure",
+    r"matplotlib\.figure\.FigureBase",
+    r"pygments\.formatters\.HtmlFormatter",
+)
+nitpick_ignore_regex = [
+    *[("py:class", target) for target in bad_classes],
+    # we demo some `urllib` docs on our site; don't care that its xrefs fail to resolve
+    ("py:obj", r"urllib\.parse\.(Defrag|Parse|Split)Result(Bytes)?\.(count|index)"),
+    # the kitchen sink pages include some intentional errors
+    ("token", r"(suite|expression|target)"),
+]
+
 # -- application setup -------------------------------------------------------
 
 
diff --git a/readthedocs.yml b/readthedocs.yml
deleted file mode 100644
index 5f057c9ae..000000000
--- a/readthedocs.yml
+++ /dev/null
@@ -1,22 +0,0 @@
-version: 2
-formats:
-  - htmlzip
-
-# build with latest available ubuntu version
-build:
-  os: ubuntu-20.04
-  tools:
-    python: "3.10"
-  apt_packages:
-    - graphviz
-  jobs:
-    # build the gallery of themes before building the doc
-    post_install:
-      - pip install playwright
-      - playwright install chromium
-      - python ./docs/scripts/generate_gallery_images.py
-
-python:
-  install:
-    - method: pip
-      path: .[doc]
diff --git a/tests/utils/check_warnings.py b/tests/utils/check_warnings.py
index f36a6172e..47813d011 100644
--- a/tests/utils/check_warnings.py
+++ b/tests/utils/check_warnings.py
@@ -30,8 +30,8 @@ def check_warnings(file: Path) -> bool:
     print("\n=== Sphinx Warnings test ===\n")
 
     # find the file where all the known warnings are stored
-    warning_file = Path(__file__).parent.parent / "warning_list.txt"
-    extra_warning_file = Path(__file__).parent.parent / "intermittent_warning_list.txt"
+    warning_file = Path(__file__).parents[1] / "warning_list.txt"
+    extra_warning_file = Path(__file__).parents[1] / "intermittent_warning_list.txt"
 
     received_warnings = escape_ansi(file.read_text()).strip().split("\n")
     expected_warnings = warning_file.read_text().strip().split("\n")
diff --git a/tox.ini b/tox.ini
index ac4f17675..5bfa951ba 100644
--- a/tox.ini
+++ b/tox.ini
@@ -108,7 +108,7 @@ extras = {[testenv:docs-no-checks]extras}
 deps =
     py39-sphinx61-docs: sphinx~=6.1.0
 commands =
-    sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
+    sphinx-build -b html docs/ docs/_build/html -nTv -w warnings.txt {posargs}
     python tests/utils/check_warnings.py
 
 # recommended for local development, this command will build the PST documentation
@@ -122,7 +122,7 @@ set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
 extras = {[testenv:docs-no-checks]extras}
 package = editable
 commands =
-    sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
+    sphinx-build -b html docs/ docs/_build/html -nTv -w warnings.txt {posargs}
     python tests/utils/check_warnings.py
 
 # build the docs with live-reload, if you are working on the docs only (no theme changes) the best option is to call