docs: use Sphinx 8 (#1303)

Don't merge!

I tried to used Sphinx 8, but `furo` (style sheet / look) has only
recently begun supporting 8 and there's no release yet. If we wait a
month to a quarter, we should be able move straight to 8.

I was able to get Sphinx 7 to work, would need to clean up the PR if we
decided to merge this.

docs/custom_conf.py

@@ -37,6 +37,7 @@ def _compute_navigation_tree(context):
     r"""^ ([\w.]+::)?            # explicit module name
           ([\w.]+\.)?            # module and/or class name(s)
           ([^.()]+)  \s*         # thing name
+          (?: \[\s*(.*)\s*])?    # optional: type parameters list, Sphinx 7&8
           (?: \((.*)\)           # optional: arguments
            (?:\s* -> \s* (.*))?  #           return annotation
           )? $                   # and nothing more

docs/requirements.txt

@@ -1,40 +1,54 @@
 #
-# This file is autogenerated by pip-compile with Python 3.11
+# This file is autogenerated by pip-compile with Python 3.12
 # by the following command:
 #
 #    pip-compile --extra=docs --output-file=docs/requirements.txt pyproject.toml
 #
-alabaster==0.7.16
+alabaster==1.0.0
     # via sphinx
-babel==2.14.0
+anyio==4.4.0
+    # via
+    #   starlette
+    #   watchfiles
+babel==2.16.0
     # via sphinx
 beautifulsoup4==4.12.3
     # via
     #   canonical-sphinx-extensions
     #   furo
     #   pyspelling
-bracex==2.4
+bracex==2.5
     # via wcmatch
-canonical-sphinx-extensions==0.0.20
+canonical-sphinx-extensions==0.0.23
     # via ops (pyproject.toml)
 certifi==2024.7.4
     # via requests
 charset-normalizer==3.3.2
     # via requests
+click==8.1.7
+    # via uvicorn
 colorama==0.4.6
     # via sphinx-autobuild
-docutils==0.19
+docutils==0.21.2
     # via
     #   canonical-sphinx-extensions
     #   myst-parser
     #   sphinx
     #   sphinx-tabs
-furo==2024.1.29
+furo==2024.8.6
     # via ops (pyproject.toml)
+gitdb==4.0.11
+    # via gitpython
+gitpython==3.1.43
+    # via canonical-sphinx-extensions
+h11==0.14.0
+    # via uvicorn
 html5lib==1.1
     # via pyspelling
 idna==3.7
-    # via requests
+    # via
+    #   anyio
+    #   requests
 imagesize==1.4.1
     # via sphinx
 jinja2==3.1.4
@@ -43,53 +57,53 @@ jinja2==3.1.4
     #   sphinx
 linkify-it-py==2.0.3
     # via ops (pyproject.toml)
-livereload==2.6.3
-    # via sphinx-autobuild
-lxml==5.2.1
+lxml==5.3.0
     # via pyspelling
-markdown==3.6
+markdown==3.7
     # via pyspelling
 markdown-it-py==3.0.0
     # via
     #   mdit-py-plugins
     #   myst-parser
 markupsafe==2.1.5
     # via jinja2
-mdit-py-plugins==0.4.0
+mdit-py-plugins==0.4.1
     # via myst-parser
 mdurl==0.1.2
     # via markdown-it-py
-myst-parser==2.0.0
+myst-parser==4.0.0
     # via ops (pyproject.toml)
-packaging==24.0
+packaging==24.1
     # via sphinx
-pygments==2.17.2
+pygments==2.18.0
     # via
     #   furo
     #   sphinx
     #   sphinx-tabs
 pyspelling==2.10
     # via ops (pyproject.toml)
-pyyaml==6.0.1
+pyyaml==6.0.2
     # via
     #   myst-parser
     #   ops (pyproject.toml)
     #   pyspelling
-requests==2.32.0
+requests==2.32.3
     # via
     #   canonical-sphinx-extensions
     #   sphinx
 six==1.16.0
-    # via
-    #   html5lib
-    #   livereload
+    # via html5lib
+smmap==5.0.1
+    # via gitdb
+sniffio==1.3.1
+    # via anyio
 snowballstemmer==2.2.0
     # via sphinx
-soupsieve==2.5
+soupsieve==2.6
     # via
     #   beautifulsoup4
     #   pyspelling
-sphinx==6.2.1
+sphinx==8.0.2
     # via
     #   canonical-sphinx-extensions
     #   furo
@@ -103,43 +117,49 @@ sphinx==6.2.1
     #   sphinx-tabs
     #   sphinxcontrib-jquery
     #   sphinxext-opengraph
-sphinx-autobuild==2024.2.4
+sphinx-autobuild==2024.4.16
     # via ops (pyproject.toml)
 sphinx-basic-ng==1.0.0b2
     # via furo
 sphinx-copybutton==0.5.2
     # via ops (pyproject.toml)
-sphinx-design==0.5.0
+sphinx-design==0.6.1
     # via ops (pyproject.toml)
-sphinx-notfound-page==1.0.0
+sphinx-notfound-page==1.0.4
     # via ops (pyproject.toml)
 sphinx-tabs==3.4.5
     # via ops (pyproject.toml)
-sphinxcontrib-applehelp==1.0.8
+sphinxcontrib-applehelp==2.0.0
     # via sphinx
-sphinxcontrib-devhelp==1.0.6
+sphinxcontrib-devhelp==2.0.0
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.5
+sphinxcontrib-htmlhelp==2.1.0
     # via sphinx
 sphinxcontrib-jquery==4.1
     # via ops (pyproject.toml)
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.7
+sphinxcontrib-qthelp==2.0.0
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.10
+sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
 sphinxext-opengraph==0.9.1
     # via ops (pyproject.toml)
-tornado==6.4.1
-    # via livereload
+starlette==0.38.2
+    # via sphinx-autobuild
 uc-micro-py==1.0.3
     # via linkify-it-py
 urllib3==2.2.2
     # via requests
-wcmatch==8.5.1
+uvicorn==0.30.6
+    # via sphinx-autobuild
+watchfiles==0.23.0
+    # via sphinx-autobuild
+wcmatch==9.0
     # via pyspelling
 webencodings==0.5.1
     # via html5lib
-websocket-client==1.7.0
+websocket-client==1.8.0
     # via ops (pyproject.toml)
+websockets==12.0
+    # via sphinx-autobuild

pyproject.toml

@@ -28,7 +28,7 @@ docs = [
     "linkify-it-py",
     "myst-parser",
     "pyspelling",
-    "sphinx==6.2.1",
+    "sphinx ~= 8.0.0",
     "sphinx-autobuild",
     "sphinx-copybutton",
     "sphinx-design",