fix ReadTheDocs: replace notebook symlink with copy and pin Sphinx <9

The notebook images were broken because docs/source/notebooks is a
symlink to ../../notebooks. nbsphinx extracts images to _build/doctrees/
and references them with relative paths, but the symlink causes those
paths to resolve from the wrong directory (see nbsphinx issue #49).

Fix by adding a pre_build job that replaces the symlink with a real copy.
Also pin sphinx>=8.0,<9 since nbsphinx 0.9.8 only re-enabled 8.2+
support and Sphinx 9 is untested.

Author: katosh

docs/requirements.txt

@@ -4,7 +4,8 @@ sphinx-autodocgen
 sphinx-github-style>=1.2.2
 sphinx-mdinclude
 m2r2
-nbsphinx
+nbsphinx>=0.9.8
+sphinx>=8.0,<9
 furo
 typing-extensions
 IPython

readthedocs.yaml

@@ -6,6 +6,10 @@ build:
     python: "3.11"
   apt_packages:
     - pandoc
+  jobs:
+    pre_build:
+      - rm docs/source/notebooks
+      - cp -r notebooks docs/source/notebooks
 
 sphinx:
    configuration: docs/source/conf.py