Update sphinx (#3070)

* Bump what Python version `docs-requirements.txt` is for

* Update `__module__` before GenericAlias makes a copy

* Reference SSLStream correctly

* Explain >=2

* fix & extend comment on math.inf & types.FrameType workaround

---------

Co-authored-by: jakkdl <h6+github@pm.me>

.github/workflows/autodeps.yml

@@ -31,7 +31,7 @@ jobs:
           python -m pip install -U pip pre-commit
           python -m pip install -r test-requirements.txt
           uv pip compile --universal --python-version=3.8 --upgrade test-requirements.in -o test-requirements.txt
-          uv pip compile --universal --python-version=3.8 --upgrade docs-requirements.in -o docs-requirements.txt
+          uv pip compile --universal --python-version=3.11 --upgrade docs-requirements.in -o docs-requirements.txt
           pre-commit autoupdate --jobs 0
 
       - name: Install new requirements
@@ -44,7 +44,7 @@ jobs:
       - name: uv
         run: |
           uv pip compile --universal --python-version=3.8 test-requirements.in -o test-requirements.txt
-          uv pip compile --universal --python-version=3.8 docs-requirements.in -o docs-requirements.txt
+          uv pip compile --universal --python-version=3.11 docs-requirements.in -o docs-requirements.txt
 
       - name: Commit changes and create automerge PR
         env:

check.sh

@@ -81,7 +81,7 @@ echo "::group::Pip Compile - Tests"
 uv pip compile --universal --python-version=3.8 test-requirements.in -o test-requirements.txt
 echo "::endgroup::"
 echo "::group::Pip Compile - Docs"
-uv pip compile --universal --python-version=3.8 docs-requirements.in -o docs-requirements.txt
+uv pip compile --universal --python-version=3.11 docs-requirements.in -o docs-requirements.txt
 echo "::endgroup::"
 
 if git status --porcelain | grep -q "requirements.txt"; then

docs-requirements.in

@@ -2,7 +2,8 @@
 # sphinx 5.3 doesn't work with our _NoValue workaround
 sphinx >= 6.0
 jinja2
-sphinx_rtd_theme
+# >= is necessary to prevent `uv` from selecting a `Sphinx` version this does not support
+sphinx_rtd_theme >= 2
 sphinxcontrib-jquery
 sphinxcontrib-trio
 towncrier

docs-requirements.txt

@@ -1,6 +1,6 @@
 # This file was autogenerated by uv via the following command:
-#    uv pip compile --universal --python-version=3.8 docs-requirements.in -o docs-requirements.txt
-alabaster==0.7.13
+#    uv pip compile --universal --python-version=3.11 docs-requirements.in -o docs-requirements.txt
+alabaster==0.7.16
     # via sphinx
 attrs==24.2.0
     # via
@@ -40,12 +40,6 @@ imagesize==1.4.1
     # via sphinx
 immutables==0.20
     # via -r docs-requirements.in
-importlib-metadata==8.4.0 ; python_full_version < '3.10'
-    # via
-    #   sphinx
-    #   towncrier
-importlib-resources==6.4.3 ; python_full_version < '3.10'
-    # via towncrier
 jinja2==3.1.4
     # via
     #   -r docs-requirements.in
@@ -63,8 +57,6 @@ pygments==2.18.0
     # via sphinx
 pyopenssl==24.2.1
     # via -r docs-requirements.in
-pytz==2024.1 ; python_full_version < '3.9'
-    # via babel
 requests==2.32.3
     # via sphinx
 sniffio==1.3.1
@@ -75,7 +67,7 @@ sortedcontainers==2.4.0
     # via -r docs-requirements.in
 soupsieve==2.6
     # via beautifulsoup4
-sphinx==7.1.2
+sphinx==7.4.7
     # via
     #   -r docs-requirements.in
     #   sphinx-codeautolink
@@ -89,11 +81,11 @@ sphinx-hoverxref==1.4.0
     # via -r docs-requirements.in
 sphinx-rtd-theme==2.0.0
     # via -r docs-requirements.in
-sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-applehelp==2.0.0
     # via sphinx
-sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-devhelp==2.0.0
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-htmlhelp==2.1.0
     # via sphinx
 sphinxcontrib-jquery==4.1
     # via
@@ -102,19 +94,13 @@ sphinxcontrib-jquery==4.1
     #   sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-qthelp==2.0.0
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
 sphinxcontrib-trio==1.1.2
     # via -r docs-requirements.in
-tomli==2.0.1 ; python_full_version < '3.11'
-    # via towncrier
 towncrier==24.7.1
     # via -r docs-requirements.in
 urllib3==2.2.2
     # via requests
-zipp==3.20.0 ; python_full_version < '3.10'
-    # via
-    #   importlib-metadata
-    #   importlib-resources

docs/source/conf.py

@@ -243,12 +243,14 @@ def add_mapping(
 
     # This has been removed in Py3.12, so add a link to the 3.11 version with deprecation warnings.
     add_mapping("method", "pathlib", "Path.link_to", "3.11")
+
     # defined in py:data in objects.inv, but sphinx looks for a py:class
+    # see https://github.com/sphinx-doc/sphinx/issues/10974
+    # to dump the objects.inv for the stdlib, you can run
+    # python -m sphinx.ext.intersphinx http://docs.python.org/3/objects.inv
     add_mapping("class", "math", "inf")
-    # `types.FrameType.__module__` is "builtins", so sphinx looks for
-    # builtins.FrameType.
-    # See https://github.com/sphinx-doc/sphinx/issues/11802
     add_mapping("class", "types", "FrameType")
+
     # new in py3.12, and need target because sphinx is unable to look up
     # the module of the object if compiling on <3.12
     if not hasattr(collections.abc, "Buffer"):

src/trio/_abc.py

@@ -691,6 +691,14 @@ async def __anext__(self) -> ReceiveType:
             raise StopAsyncIteration from None
 
 
+# these are necessary for Sphinx's :show-inheritance: with type args.
+# (this should be removed if possible)
+# see: https://github.com/python/cpython/issues/123250
+SendChannel.__module__ = SendChannel.__module__.replace("_abc", "abc")
+ReceiveChannel.__module__ = ReceiveChannel.__module__.replace("_abc", "abc")
+Listener.__module__ = Listener.__module__.replace("_abc", "abc")
+
+
 class Channel(SendChannel[T], ReceiveChannel[T]):
     """A standard interface for interacting with bidirectional channels.
 
@@ -700,3 +708,7 @@ class Channel(SendChannel[T], ReceiveChannel[T]):
     """
 
     __slots__ = ()
+
+
+# see above
+Channel.__module__ = Channel.__module__.replace("_abc", "abc")

src/trio/_ssl.py

@@ -893,6 +893,10 @@ async def wait_send_all_might_not_block(self) -> None:
                 await self.transport_stream.wait_send_all_might_not_block()
 
 
+# this is necessary for Sphinx, see also `_abc.py`
+SSLStream.__module__ = SSLStream.__module__.replace("._ssl", "")
+
+
 @final
 class SSLListener(Listener[SSLStream[T_Stream]]):
     """A :class:`~trio.abc.Listener` for SSL/TLS-encrypted servers.