docs: add cross-ref

mkdocs.yml

@@ -58,13 +58,16 @@ markdown_extensions:
   - pymdownx.superfences
 plugins:
   - search
+  - autorefs
   - mkdocstrings:
       handlers:
         python:
           paths:
             - src
           import:
-            - https://docs.python.org/3/objects.inv
+            - url: https://docs.python.org/3/objects.inv
+              domains: [std, py]
+            - https://typing-extensions.readthedocs.io/en/stable/objects.inv
             - https://anyio.readthedocs.io/en/stable/objects.inv
           options:
             # general

src/async_wrapper/convert/_async.py

@@ -42,35 +42,35 @@ def sync_to_async(func: Callable[_P, _T]) -> Callable[_P, Awaitable[_T]]:
         An asynchronous function
         that behaves equivalently to the input synchronous function.
 
-    Example:
-        .. code-block:: python
+    Examples:
+        ```python
+        import time
 
-            import time
+        import anyio
 
-            import anyio
+        from async_wrapper import sync_to_async
 
-            from async_wrapper import sync_to_async
 
+        @sync_to_async
+        def test(x: int) -> int:
+            print(f"[{x}] test: start")
+            time.sleep(1)
+            print(f"[{x}] test: end")
+            return x
 
-            @sync_to_async
-            def test(x: int) -> int:
-                print(f"[{x}] test: start")
-                time.sleep(1)
-                print(f"[{x}] test: end")
-                return x
 
+        async def main() -> None:
+            start = time.perf_counter()
+            async with anyio.create_task_group() as task_group:
+                for i in range(4):
+                    task_group.start_soon(test, i)
+            end = time.perf_counter()
+            assert end - start < 1.1
 
-            async def main() -> None:
-                start = time.perf_counter()
-                async with anyio.create_task_group() as task_group:
-                    for i in range(4):
-                        task_group.start_soon(test, i)
-                end = time.perf_counter()
-                assert end - start < 1.1
 
-
-            if __name__ == "__main__":
-                anyio.run(main)
+        if __name__ == "__main__":
+            anyio.run(main)
+        ```
     """
     from async_wrapper.convert._sync.main import Sync
 

src/async_wrapper/convert/_sync/main.py

@@ -82,58 +82,58 @@ def async_to_sync(
         A synchronous function.
 
     Example:
-        .. code-block:: python
-
-            import asyncio
-            import time
-
-            import anyio
-            import sniffio
-
-            from async_wrapper import async_to_sync
-
-
-            @async_to_sync
-            async def test(x: int) -> int:
-                backend = sniffio.current_async_library()
-                if backend == "asyncio":
-                    loop = asyncio.get_running_loop()
-                    print(backend, loop)
-                else:
-                    print(backend)
-                await anyio.sleep(1)
-                return x
-
-
-            def main() -> None:
-                start = time.perf_counter()
-                result = test(1)
-                end = time.perf_counter()
-                assert result == 1
-                assert end - start < 1.1
-
-
-            async def async_main() -> None:
-                start = time.perf_counter()
-                result = test(1)
-                end = time.perf_counter()
-                assert result == 1
-                assert end - start < 1.1
-
-
-            if __name__ == "__main__":
-                main()
-                anyio.run(
-                    async_main,
-                    backend="asyncio",
-                    backend_options={"use_uvloop": True},
-                )
-                anyio.run(
-                    async_main,
-                    backend="asyncio",
-                    backend_options={"use_uvloop": True},
-                )
-                anyio.run(async_main, backend="trio")
+        ```python
+        import asyncio
+        import time
+
+        import anyio
+        import sniffio
+
+        from async_wrapper import async_to_sync
+
+
+        @async_to_sync
+        async def test(x: int) -> int:
+            backend = sniffio.current_async_library()
+            if backend == "asyncio":
+                loop = asyncio.get_running_loop()
+                print(backend, loop)
+            else:
+                print(backend)
+            await anyio.sleep(1)
+            return x
+
+
+        def main() -> None:
+            start = time.perf_counter()
+            result = test(1)
+            end = time.perf_counter()
+            assert result == 1
+            assert end - start < 1.1
+
+
+        async def async_main() -> None:
+            start = time.perf_counter()
+            result = test(1)
+            end = time.perf_counter()
+            assert result == 1
+            assert end - start < 1.1
+
+
+        if __name__ == "__main__":
+            main()
+            anyio.run(
+                async_main,
+                backend="asyncio",
+                backend_options={"use_uvloop": True},
+            )
+            anyio.run(
+                async_main,
+                backend="asyncio",
+                backend_options={"use_uvloop": True},
+            )
+            anyio.run(async_main, backend="trio")
+        ```
     """
     if callable(func_or_awaitable):
         from async_wrapper.convert._async import Async

src/async_wrapper/exception.py

@@ -52,9 +52,11 @@ class QueueClosedError(QueueError):
     Error that occurs when attempting to get from or put into a closed queue.
 
     This error is different from QueueBrokenError.
-        :exc:`QueueBrokenError` is an unintended error.
 
-        :exc:`QueueClosedError` is an error deliberately raised.
+    - [`QueueBrokenError`][async_wrapper.exception.QueueBrokenError]
+    is an unintended error.
+    - [`QueueClosedError`][async_wrapper.exception.QueueClosedError]
+    is an error deliberately raised.
     """
 
 
@@ -63,9 +65,11 @@ class QueueBrokenError(QueueError):
     Error that occurs when trying to get from or put into a closed queue.
 
     This error is different from QueueClosedError.
-        :exc:`QueueClosedError` is an error deliberately raised.
 
-        :exc:`QueueBrokenError` is an unintended error.
+    - [`QueueClosedError`][async_wrapper.exception.QueueClosedError]
+    is an error deliberately raised.
+    - [`QueueBrokenError`][async_wrapper.exception.QueueBrokenError]
+    is an unintended error.
     """
 
 

src/async_wrapper/queue.py

@@ -43,41 +43,41 @@
 
 class Queue(Generic[_T]):
     """
-    obtained from :class:`asyncio.Queue`
+    obtained from [`asyncio.Queue`][]
 
-    Example:
-        .. code-block:: python
+    Examples:
+        ```python
+        from __future__ import annotations
 
-            from __future__ import annotations
+        from typing import Any
 
-            from typing import Any
+        import anyio
 
-            import anyio
+        from async_wrapper import Queue
 
-            from async_wrapper import Queue
 
+        async def aput(queue: Queue[Any], value: Any) -> None:
+            async with queue:
+                await queue.aput(value)
 
-            async def aput(queue: Queue[Any], value: Any) -> None:
-                async with queue:
-                    await queue.aput(value)
 
+        async def main() -> None:
+            queue: Queue[Any] = Queue(10)
 
-            async def main() -> None:
-                queue: Queue[Any] = Queue(10)
+            async with anyio.create_task_group() as task_group:
+                async with queue.aputter:
+                    for i in range(10):
+                        task_group.start_soon(aput, queue.clone.putter, i)
 
-                async with anyio.create_task_group() as task_group:
-                    async with queue.aputter:
-                        for i in range(10):
-                            task_group.start_soon(aput, queue.clone.putter, i)
+            async with queue.agetter:
+                result = {x async for x in queue}
 
-                async with queue.agetter:
-                    result = {x async for x in queue}
+            assert result == set(range(10))
 
-                assert result == set(range(10))
 
-
-            if __name__ == "__main__":
-                anyio.run(main)
+        if __name__ == "__main__":
+            anyio.run(main)
+        ```
     """
 
     __slots__ = ("_putter", "_getter", "_close_putter", "_close_getter")
@@ -573,13 +573,13 @@ def __repr__(self) -> str:
 
 def create_queue(max_size: float | None = None) -> Queue[Any]:
     """
-    create queue like :class:`asyncio.Queue`
+    create queue like [`asyncio.Queue`][]
 
     Args:
         max_size: queue size. Defaults to None.
 
     Returns:
-        new :obj:`Queue` using :class:`anyio.abc.ObjectStream`
+        new [`Queue`][async_wrapper.Queue] using [`anyio.abc.ObjectStream`][]
     """
     return Queue(max_size)
 

src/async_wrapper/task_group/task_group.py

@@ -24,36 +24,36 @@
 
 class TaskGroupWrapper(_TaskGroup):
     """
-    wrap :class:`anyio.abc.TaskGroup`
+    wrap [`anyio.abc.TaskGroup`][]
 
-    Example:
-        .. code-block:: python
+    Examples:
+        ```python
+        import anyio
 
-            import anyio
+        from async_wrapper import TaskGroupWrapper
 
-            from async_wrapper import TaskGroupWrapper
 
+        async def test(x: int) -> int:
+            await anyio.sleep(0.1)
+            return x
 
-            async def test(x: int) -> int:
-                await anyio.sleep(0.1)
-                return x
 
+        async def main() -> None:
+            async with anyio.create_task_group() as task_group:
+                async with TaskGroupWrapper(task_group) as tg:
+                    func = tg.wrap(test)
+                    soon_1 = func(1)
+                    soon_2 = func(2)
 
-            async def main() -> None:
-                async with anyio.create_task_group() as task_group:
-                    async with TaskGroupWrapper(task_group) as tg:
-                        func = tg.wrap(test)
-                        soon_1 = func(1)
-                        soon_2 = func(2)
+            assert soon_1.is_ready
+            assert soon_2.is_ready
+            assert soon_1.value == 1
+            assert soon_2.value == 2
 
-                assert soon_1.is_ready
-                assert soon_2.is_ready
-                assert soon_1.value == 1
-                assert soon_2.value == 2
 
-
-            if __name__ == "__main__":
-                anyio.run(main)
+        if __name__ == "__main__":
+            anyio.run(main)
+        ```
     """
 
     __slots__ = ("_task_group", "_active_self")
@@ -115,9 +115,9 @@ def wrap(
 
         Args:
             func: The target function to be wrapped.
-            semaphore: An :obj:`anyio.abc.Semaphore`. Defaults to None.
-            limiter: An :obj:`anyio.abc.CapacityLimiter`. Defaults to None.
-            lock: An :obj:`anyio.abc.Lock`. Defaults to None.
+            semaphore: An [`anyio.Semaphore`][]. Defaults to None.
+            limiter: An [`anyio.CapacityLimiter`][]. Defaults to None.
+            lock: An [`anyio.Lock`][]. Defaults to None.
 
         Returns:
             The wrapped function.
@@ -126,7 +126,7 @@ def wrap(
 
 
 class SoonWrapper(Generic[_P, _T]):
-    """wrapped func using in :class:`TaskGroupWrapper`"""
+    """wrapped func using in `TaskGroupWrapper`"""
 
     __slots__ = ("func", "task_group", "semaphore", "limiter", "lock", "_wrapped")
 
@@ -190,11 +190,11 @@ def copy(
         Create a copy of this object.
 
         Args:
-            semaphore: An :obj:`anyio.abc.Semaphore`.
+            semaphore: An [`anyio.Semaphore`][].
                 If provided, it will overwrite the existing semaphore. Defaults to None.
-            limiter: An :obj:`anyio.abc.CapacityLimiter`.
+            limiter: An [`anyio.CapacityLimiter`][].
                 If provided, it will overwrite the existing limiter. Defaults to None.
-            lock: An :obj:`anyio.abc.Lock`.
+            lock: An [`anyio.Lock`][].
                 If provided, it will overwrite the existing lock. Defaults to None.
 
         Returns:
@@ -216,7 +216,7 @@ def create_task_group_wrapper() -> TaskGroupWrapper:
     create new task group wrapper
 
     Returns:
-        new :obj:`TaskGroupWrapper`
+        new [`TaskGroupWrapper`][async_wrapper.task_group.task_group.TaskGroupWrapper]
     """
     return TaskGroupWrapper(_create_task_group())