Successfully build docs on Windows on CPython 3.13

Author: A5rocks

src/trio/_core/__init__.py

@@ -73,7 +73,7 @@
 from ._unbounded_queue import UnboundedQueue, UnboundedQueueStatistics
 
 # Windows imports
-if sys.platform == "win32":
+if sys.platform == "win32" or "sphinx.ext.autodoc" in sys.modules:
     from ._run import (
         current_iocp,
         monitor_completion_key,
@@ -83,7 +83,9 @@
         write_overlapped,
     )
 # Kqueue imports
-elif sys.platform != "linux" and sys.platform != "win32":
+if (
+    sys.platform != "linux" and sys.platform != "win32"
+) or "sphinx.ext.autodoc" in sys.modules:
     from ._run import current_kqueue, monitor_kevent, wait_kevent
 
 del sys  # It would be better to import sys as _sys, but mypy does not understand it

src/trio/_core/_run.py

@@ -2960,6 +2960,12 @@ def in_trio_task() -> bool:
     return hasattr(GLOBAL_RUN_CONTEXT, "task")
 
 
+# export everything for the documentation
+if "sphinx.ext.autodoc" in sys.modules:
+    from ._generated_io_epoll import *
+    from ._generated_io_kqueue import *
+    from ._generated_io_windows import *
+
 if sys.platform == "win32":
     from ._generated_io_windows import *
     from ._io_windows import (
@@ -2985,7 +2991,7 @@ def in_trio_task() -> bool:
     _patchers = sorted({"eventlet", "gevent"}.intersection(sys.modules))
     if _patchers:
         raise NotImplementedError(
-            "unsupported platform or primitives trio depends on are monkey-patched out by "
+            "unsupported platform or primitives Trio depends on are monkey-patched out by "
             + ", ".join(_patchers),
         )
 

src/trio/_highlevel_socket.py

@@ -14,10 +14,18 @@
 if TYPE_CHECKING:
     from collections.abc import Generator
 
-    from typing_extensions import Buffer
-
     from ._socket import SocketType
 
+import sys
+
+if sys.version_info >= (3, 12):
+    # NOTE: this isn't in the `TYPE_CHECKING` since for some reason
+    # sphinx doesn't autoreload this module for SocketStream
+    # (hypothesis: it's our module renaming magic)
+    from collections.abc import Buffer
+elif TYPE_CHECKING:
+    from typing_extensions import Buffer
+
 # XX TODO: this number was picked arbitrarily. We should do experiments to
 # tune it. (Or make it dynamic -- one idea is to start small and increase it
 # if we observe single reads filling up the whole buffer, at least within some
@@ -152,6 +160,7 @@ def setsockopt(self, level: int, option: int, value: int | Buffer) -> None: ...
     @overload
     def setsockopt(self, level: int, option: int, value: None, length: int) -> None: ...
 
+    # TODO: rename `length` to `optlen`
     def setsockopt(
         self,
         level: int,

src/trio/_path.py

@@ -39,8 +39,18 @@ async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
 
         update_wrapper(wrapper, wrapped)
         if wrapped.__doc__:
+            module = wrapped.__module__
+            # these are exported specially from CPython's intersphinx inventory
+            module = module.replace("pathlib._local", "pathlib")
+            module = module.replace("pathlib._abc", "pathlib")
+
+            name = wrapped.__qualname__
+            name = name.replace(
+                "PathBase", "Path"
+            )  # I'm not sure why this is necessary
+
             wrapper.__doc__ = (
-                f"Like :meth:`~{wrapped.__module__}.{wrapped.__qualname__}`, but async.\n"
+                f"Like :meth:`~{module}.{name}`, but async.\n"
                 f"\n"
                 f"{cleandoc(wrapped.__doc__)}\n"
             )
@@ -245,6 +255,9 @@ def __repr__(self) -> str:
         full_match = _wrap_method(pathlib.Path.full_match)
 
 
+Path.relative_to.__doc__ = Path.relative_to.__doc__.replace(" `..` ", " ``..`` ")
+
+
 @final
 class PosixPath(Path, pathlib.PurePosixPath):
     """An async :class:`pathlib.PosixPath` that executes blocking methods in :meth:`trio.to_thread.run_sync`."""

src/trio/lowlevel.py

@@ -62,7 +62,7 @@
 # Uses `from x import y as y` for compatibility with `pyright --verifytypes` (#2625)
 
 
-if sys.platform == "win32":
+if sys.platform == "win32" or "sphinx.ext.autodoc" in sys.modules:
     # Windows symbols
     from ._core import (
         current_iocp as current_iocp,
@@ -73,13 +73,15 @@
         write_overlapped as write_overlapped,
     )
     from ._wait_for_object import WaitForSingleObject as WaitForSingleObject
-else:
+
+if sys.platform != "win32" or "sphinx.ext.autodoc" in sys.modules:
     # Unix symbols
-    if _os.name == "posix":
-        from ._unix_pipes import FdStream as FdStream
+    from ._unix_pipes import FdStream as FdStream
 
     # Kqueue-specific symbols
-    if sys.platform != "linux" and (_t.TYPE_CHECKING or not hasattr(_select, "epoll")):
+    if (
+        sys.platform != "linux" and (_t.TYPE_CHECKING or not hasattr(_select, "epoll"))
+    ) or "sphinx.ext.autodoc" in sys.modules:
         from ._core import (
             current_kqueue as current_kqueue,
             monitor_kevent as monitor_kevent,