Merge branch 'aioretryproto-doc'

CHANGELOG.md

@@ -8,6 +8,7 @@
 ### New
 
 ### Changes
+* update AioretryProtocol documentation
 
 ### Fixes
 

docs/source/kaioretry.rst

@@ -14,3 +14,10 @@ The :py:class:`kaioretry.Context` class
 
 .. automodule:: kaioretry.context
    :members:
+
+
+Misc Types
+----------
+
+.. automodule:: kaioretry.types
+   :members:

kaioretry/types.py

@@ -1,4 +1,6 @@
-"""Custom types used by kaioretry"""
+"""
+Kaioretry defines a bunch
+"""
 
 
 from typing import TypeAlias, TypeVar, ParamSpec, Any, overload
@@ -30,6 +32,7 @@
 
 
 FuncParam = ParamSpec('FuncParam')
+
 FuncRetVal = TypeVar('FuncRetVal')
 
 Function: TypeAlias = Callable[..., Any]
@@ -47,7 +50,11 @@
 
 class AioretryProtocol(Protocol):
 
-    """The type of the main aioretry decorator"""
+    """The :py:class:`typing.Protocol` describing the behaviour of the
+    :py:func:`~kaioretry.aioretry` decorator.
+
+    .. automethod:: __call__
+    """
 
     @overload
     def __call__(self, func: AwaitableFunc[FuncParam, FuncRetVal]) \
@@ -61,4 +68,14 @@ def __call__(self, func: Callable[FuncParam, FuncRetVal]) \
 
     def __call__(self, func: AnyFunction[FuncParam, FuncRetVal]) \
             -> AioretryCoro[FuncParam, FuncRetVal]:
+        """When called (to decorate a function), an aioretry decorator will...
+
+        :param func: ... take a function as input...
+
+        :returns: and, if ``func`` returns an
+          :py:class:`~collections.abc.Awaitable`, then return a same-signature
+          same-type coroutine function. If ``func`` does not, then return a
+          same-signature *coroutine* function that, once awaited, return
+          ``func`` original return value.
+        """
         ...

pyproject.toml

@@ -38,9 +38,9 @@ pytest-cov = ">=4"
 optional = true
 
 [tool.poetry.group.sphinx.dependencies]
-sphinx = ">=5"
+sphinx = ">=7"
 sphinx-autodoc-typehints = ">=1.17"
-sphinx-rtd-theme = "*"
+sphinx-rtd-theme = ">=2"
 
 [build-system]
 requires = ["poetry-core>=1.4.0"]