MAINT - Update ReadTheDocs settings file (#2083)

ReadTheDocs is making some changes that affect us. Will leave
self-review to explain the changes.

closes #2101

---------

Co-authored-by: Tania Allard <[email protected]>

.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

docs/conf.py

@@ -292,6 +292,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 -------------------------------------------------------
 
 

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")

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