docs: Use Zensical support for mkdocs-autoapi to auto-generate API documentation (#222)

- https://github.com/zensical/zensical/releases/tag/v0.0.66
- https://mkdocs-autoapi.readthedocs.io/en/latest/usage/#controlling-output

Signed-off-by: Edgar Ramírez Mondragón <edgarrm358@gmail.com>

Author: edgarrmondragon

.github/workflows/docs.yml

@@ -40,6 +40,9 @@ jobs:
       - name: Build documentation
         run: uvx --with tox-uv tox -e docs
 
+      - name: Check for uncommitted autogenerated docs
+        run: git diff --exit-code docs
+
       - name: Upload documentation as artifact
         id: deployment
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0

backoff/__init__.py

@@ -1,5 +1,5 @@
 """
-Function decoration for backoff and retry
+Function decoration for backoff and retry.
 
 This module provides function decorators which can be used to wrap a
 function such that it will be retried until some condition is met. It
@@ -8,8 +8,8 @@
 APIs. Somewhat more generally, it may also be of use for dynamically
 polling resources for externally generated content.
 
-For examples and full documentation see the README at
-https://github.com/python-backoff/backoff
+For examples and full documentation, see
+[the official documentation](https://backoff.readthedocs.io/en/latest/).
 """
 
 from backoff._common import Attempt

backoff/_decorator.py

@@ -307,9 +307,14 @@ def retry_context(
     Unlike `on_exception`, this doesn't wrap a whole function; it lets a
     caller retry an arbitrary block of code:
 
-        for attempt in backoff.retry_context(ValueError, backoff.expo):
-            with attempt:
-                do_something()
+    ```python
+    for attempt in backoff.retry_context(
+        ValueError,
+        backoff.expo,
+    ):
+        with attempt:
+            do_something()
+    ```
 
     Each `attempt` is a context manager: exceptions matching `exception`
     are caught, and the loop either sleeps and retries or lets the
@@ -403,9 +408,14 @@ def aretry_context(
 ) -> AsyncGenerator[Attempt, None]:
     """Async counterpart to `retry_context`, for use with `async for`.
 
-        async for attempt in backoff.aretry_context(ValueError, backoff.expo):
-            with attempt:
-                await do_something()
+    ```python
+    async for attempt in backoff.aretry_context(
+        ValueError,
+        backoff.expo,
+    ):
+        with attempt:
+            await do_something()
+    ```
 
     `giveup` and the handlers may be sync or async callables. See
     `retry_context` for the full argument reference.

backoff/_wait_gen.py

@@ -38,16 +38,14 @@ def decay(
     decay_factor: float = 1,
     min_value: float | None = None,
 ) -> Generator[float, Any, None]:
-    """Generator for exponential decay[1]:
+    """Generator for [exponential decay](https://en.wikipedia.org/wiki/Exponential_decay).
 
     Args:
         initial_value: initial quantity
         decay_factor: exponential decay constant.
         min_value: The minimum value to yield. Once the value in the
              true exponential sequence is lower than this, the value
              of min_value will forever after be yielded.
-
-    [1] https://en.wikipedia.org/wiki/Exponential_decay
     """
     # Advance past initial .send() call
     yield 0
@@ -106,23 +104,39 @@ def runtime(*, value: Callable[[Any], float]) -> Generator[float, Any, None]:
     Useful for honoring a server-specified retry delay, e.g. an HTTP
     `Retry-After` header, rather than a fixed wait sequence:
 
-        # with on_predicate, `value` receives the return value
-        @backoff.on_predicate(
-            backoff.runtime,
-            predicate=lambda r: r.status_code == 429,
-            value=lambda r: int(r.headers.get("Retry-After", 1)),
-        )
-        def get_page():
-            return requests.get(url)
-
-        # with on_exception, `value` receives the raised exception
-        @backoff.on_exception(
-            backoff.runtime,
-            RetryableError,
-            value=lambda e: e.wait_seconds,
+    ```python
+    # with on_predicate, `value` receives the return value
+    @backoff.on_predicate(
+        backoff.runtime,
+        predicate=lambda r: (
+            r.status_code
+            == 429
+        ),
+        value=lambda r: (
+            int(
+                r.headers.get(
+                    "Retry-After",
+                    1,
+                )
+            )
+        ),
+    )
+    def get_page():
+        return requests.get(
+            url
         )
-        def get_page():
-            ...
+
+
+    # with on_exception, `value` receives the raised exception
+    @backoff.on_exception(
+        backoff.runtime,
+        RetryableError,
+        value=lambda e: (
+            e.wait_seconds
+        ),
+    )
+    def get_page(): ...
+    ```
 
     Args:
         value: a callable which takes as input the decorated

docs/api/backoff/index.md

@@ -0,0 +1 @@
+::: backoff

docs/api/reference.md

@@ -0,0 +1 @@
+- [backoff](backoff/index.md)

docs/api/summary.md

@@ -56,7 +56,7 @@ This will retry the function with exponential backoff whenever a `RequestExcepti
 - [Getting Started Guide](getting-started.md) - Detailed tutorial
 - [User Guide](user-guide/decorators.md) - Complete reference
 - [Examples](examples.md) - Real-world patterns
-- [API Reference](api/reference.md) - Full API documentation
+- [API Reference](api/backoff/index.md) - Full API documentation
 
 ## Project Links
 

docs/index.md

@@ -43,7 +43,7 @@ dev = [
 ]
 docs = [
     "mkdocstrings[python]~=1.0.2",
-    "zensical==0.0.57",
+    "zensical==0.0.66",
 ]
 lint = [
     "ruff>=0.16.0",
@@ -68,10 +68,10 @@ typing = [
 ]
 
 [tool.hatch.build.targets.sdist]
-include = ["backoff", "tests"]
+include = ["/backoff", "/docs", "/tests"]
 
 [tool.hatch.build.targets.wheel]
-include = ["backoff"]
+include = ["/backoff"]
 
 [tool.tox]
 requires = [ "tox>=4.61", "tox-uv" ]

pyproject.toml

@@ -51,7 +51,9 @@ mkdocstrings-python==2.0.7
 packaging==26.3
     # via mkdocs
 pathspec==1.1.1
-    # via mkdocs
+    # via
+    #   mkdocs
+    #   zensical
 platformdirs==4.11.4
     # via mkdocs-get-deps
 pygments==2.21.0
@@ -77,5 +79,5 @@ tomli==2.4.1
     # via zensical
 watchdog==6.0.0
     # via mkdocs
-zensical==0.0.57
+zensical==0.0.66
     # via python-backoff (pyproject.toml:docs)