Allow documentation builds on Windows (#3227)

* Stop raising in `_unix_pipes`

* Successfully build docs on Windows on CPython 3.13

* Be a bit stricter about what is allowed for Unix-seeing-Windows

* Make use of these new capabilities

* Appease type checker

* Appease codecov

* More codecov appeasement

* Migrate to a single excluded line

Author: A5rocks

docs/source/reference-lowlevel.rst

@@ -274,18 +274,21 @@ TODO: these are implemented, but are currently more of a sketch than
 anything real. See `#26
 <https://github.com/python-trio/trio/issues/26>`__.
 
-.. function:: current_kqueue()
+.. autofunction:: current_kqueue()
 
-.. function:: wait_kevent(ident, filter, abort_func)
+.. autofunction:: wait_kevent(ident, filter, abort_func)
    :async:
 
-.. function:: monitor_kevent(ident, filter)
+.. autofunction:: monitor_kevent(ident, filter)
    :with: queue
 
 
 Windows-specific API
 --------------------
 
+.. note: this is a function and not `autofunction` since it relies on cffi
+   compiling some things.
+
 .. function:: WaitForSingleObject(handle)
     :async:
 
@@ -304,20 +307,20 @@ anything real. See `#26
 <https://github.com/python-trio/trio/issues/26>`__ and `#52
 <https://github.com/python-trio/trio/issues/52>`__.
 
-.. function:: register_with_iocp(handle)
+.. autofunction:: register_with_iocp(handle)
 
-.. function:: wait_overlapped(handle, lpOverlapped)
+.. autofunction:: wait_overlapped(handle, lpOverlapped)
    :async:
 
-.. function:: write_overlapped(handle, data)
+.. autofunction:: write_overlapped(handle, data)
    :async:
 
-.. function:: readinto_overlapped(handle, data)
+.. autofunction:: readinto_overlapped(handle, data)
    :async:
 
-.. function:: current_iocp()
+.. autofunction:: current_iocp()
 
-.. function:: monitor_completion_key()
+.. autofunction:: monitor_completion_key()
    :with: queue
 
 

pyproject.toml

@@ -335,7 +335,7 @@ exclude_also = [
    "@overload",
    'class .*\bProtocol\b.*\):',
    "raise NotImplementedError",
-   '.*if "sphinx" in sys.modules:',
+   '.*if "sphinx.ext.autodoc" in sys.modules:',
    'TODO: test this line',
    'if __name__ == "__main__":',
 ]

src/trio/_channel.py

@@ -35,7 +35,7 @@
     from typing_extensions import ParamSpec, Self
 
     P = ParamSpec("P")
-elif "sphinx" in sys.modules:
+elif "sphinx.ext.autodoc" in sys.modules:
     # P needs to exist for Sphinx to parse the type hints successfully.
     try:
         from typing_extensions import ParamSpec

src/trio/_core/__init__.py

@@ -5,6 +5,7 @@
 """
 
 import sys
+import typing as _t
 
 from ._entry_queue import TrioToken
 from ._exceptions import (
@@ -73,7 +74,9 @@
 from ._unbounded_queue import UnboundedQueue, UnboundedQueueStatistics
 
 # Windows imports
-if sys.platform == "win32":
+if sys.platform == "win32" or (
+    not _t.TYPE_CHECKING and "sphinx.ext.autodoc" in sys.modules
+):
     from ._run import (
         current_iocp,
         monitor_completion_key,
@@ -83,7 +86,9 @@
         write_overlapped,
     )
 # Kqueue imports
-elif sys.platform != "linux" and sys.platform != "win32":
+if (sys.platform != "linux" and sys.platform != "win32") or (
+    not _t.TYPE_CHECKING and "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

@@ -3080,6 +3080,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 (
@@ -3105,7 +3111,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"
             )
@@ -248,6 +258,10 @@ def as_uri(self) -> str:
         return pathlib.Path.as_uri(self)
 
 
+if Path.relative_to.__doc__:  # pragma: no branch
+    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/_tests/test_unix_pipes.py

@@ -22,9 +22,6 @@
 
 if posix:
     from .._unix_pipes import FdStream
-else:
-    with pytest.raises(ImportError):
-        from .._unix_pipes import FdStream
 
 
 async def make_pipe() -> tuple[FdStream, FdStream]:

src/trio/_timeouts.py

@@ -190,7 +190,7 @@ def fail_after(
 # Users don't need to know that fail_at & fail_after wraps move_on_at and move_on_after
 # and there is no functional difference. So we replace the return value when generating
 # documentation.
-if "sphinx" in sys.modules:  # pragma: no cover
+if "sphinx.ext.autodoc" in sys.modules:
     import inspect
 
     for c in (fail_at, fail_after):

src/trio/_unix_pipes.py

@@ -15,11 +15,6 @@
 
 assert not TYPE_CHECKING or sys.platform != "win32"
 
-if os.name != "posix":
-    # We raise an error here rather than gating the import in lowlevel.py
-    # in order to keep jedi static analysis happy.
-    raise ImportError
-
 # XX TODO: is this a good number? who knows... it does match the default Linux
 # pipe capacity though.
 DEFAULT_RECEIVE_SIZE: FinalType = 65536