Add docs (#16)

* De-cog

Cog is awesome, but auto-reformat is screwing with it.

* Add docs

* Conditionally install tomli

* Don't need it here

* fix edit button

Author: hynek

.github/workflows/ci.yml

@@ -25,22 +25,6 @@ jobs:
 
       - uses: hynek/build-and-inspect-python-package@v1
 
-  cog-check:
-    name: Ensure cogified files are up-to-date
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          cache: pip
-
-      - name: Prepare & run nox
-        run: |
-          python -Im pip install nox
-          python -Im nox \
-            --session cog \
-            -- --check
-
   tests:
     name: Tests on ${{ matrix.python-version }}
     runs-on: ubuntu-latest
@@ -49,18 +33,11 @@ jobs:
       fail-fast: false
       matrix:
         python-version:
-          # [[[cog
-          # import tomllib, pathlib
-          # sup = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["tool"]["supported-pythons"]
-          # for v in sup["all"]:
-          #     cog.outl(f'- "{v}"')
-          # ]]]
           - "3.8"
           - "3.9"
           - "3.10"
           - "3.11"
           - "3.12"
-          # [[[end]]]
 
     steps:
       - name: Download pre-built packages
@@ -77,7 +54,7 @@ jobs:
 
       - name: Prepare & run Nox
         run: |
-          python -Im pip install nox
+          python -Im pip install nox "tomli; python_version<'3.11'"
           python -Im nox \
             --python ${{ matrix.python-version }} \
             --sessions tests \
@@ -134,18 +111,11 @@ jobs:
       fail-fast: false
       matrix:
         python-version:
-          # [[[cog
-          # import tomllib, pathlib
-          # sup = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["tool"]["supported-pythons"]
-          # for v in sup["all"]:
-          #     cog.outl(f'- "{v}"')
-          # ]]]
           - "3.8"
           - "3.9"
           - "3.10"
           - "3.11"
           - "3.12"
-          # [[[end]]]
 
     steps:
       - name: Download pre-built packages
@@ -162,11 +132,34 @@ jobs:
 
       - name: Prepare & run Nox
         run: |
-          python -Im pip install nox
+          python -Im pip install nox "tomli; python_version<'3.11'"
           python -Im nox \
             --python ${{ matrix.python-version }} \
             --sessions mypy
 
+  docs:
+    name: Build docs & run doctests
+    runs-on: ubuntu-latest
+    needs: build-package
+    steps:
+      - name: Download pre-built packages
+        uses: actions/download-artifact@v3
+        with:
+          name: Packages
+          path: dist
+      - run: tar xf dist/*.tar.gz --strip-components=1
+      - uses: actions/setup-python@v4
+        with:
+          # Keep in sync with .readthedocs.yaml
+          python-version: "3.11"
+          cache: pip
+
+      - name: Prepare & run Nox
+        run: |
+          python -Im pip install nox
+          python -Im nox \
+            --session docs
+
   install-dev:
     name: Verify dev env
     runs-on: ${{ matrix.os }}
@@ -192,7 +185,7 @@ jobs:
     needs:
       - coverage
       - install-dev
-      - cog-check
+      - docs
       - build-package
 
     runs-on: ubuntu-latest

.gitignore

@@ -8,3 +8,4 @@ __pycache__
 dist
 t.py
 Justfile
+docs/_build

.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
         args: [--fix, --exit-non-zero-on-fix]
 
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.2.4
+    rev: v2.2.5
     hooks:
       - id: codespell
 

.readthedocs.yaml

@@ -0,0 +1,16 @@
+---
+version: 2
+formats: all
+
+build:
+  os: ubuntu-22.04
+  tools:
+    # Keep version in sync with ci.yml/docs.
+    python: "3.11"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

README.md

@@ -23,106 +23,12 @@ In practice, only a few knobs are needed (repeatedly!), though.
 - Easy _global_ deactivation for testing.
 
 
-## Usage
+## Project Information
 
-The API consists mainly of the `stamina.retry()` decorator for retrying functions and methods, and the `stamina.retry_context()` iterator / context manager combo for retrying arbitrary code blocks:
-
-<!-- example-start -->
-```python
-import datetime as dt
-
-import httpx
-
-import stamina
-
-
-@stamina.retry(on=httpx.HTTPError, attempts=3)
-def do_it(code: int) -> httpx.Response:
-    resp = httpx.get(f"https://httpbin.org/status/{code}")
-    resp.raise_for_status()
-
-    return resp
-
-# reveal_type(do_it)
-# note: Revealed type is "def (code: builtins.int) -> httpx._models.Response"
-
-for attempt in stamina.retry_context(on=httpx.HTTPError):
-    with attempt:
-        resp = httpx.get(f"https://httpbin.org/status/404")
-        resp.raise_for_status()
-```
-
-Async works with the exact same functions and arguments:
-
-```python
-@stamina.retry(
-    on=httpx.HTTPError, attempts=3, timeout=dt.timedelta(seconds=10)
-)
-async def do_it_async(code: int) -> httpx.Response:
-    async with httpx.AsyncClient() as client:
-        resp = await client.get(f"https://httpbin.org/status/{code}")
-    resp.raise_for_status()
-
-    return resp
-
-# reveal_type(do_it_async)
-# note: Revealed type is "def (code: builtins.int) -> typing.Coroutine[Any, Any, httpx._models.Response]"
-
-async def with_block(code: int) -> httpx.Response:
-    async for attempt in stamina.retry_context(on=httpx.HTTPError, attempts=3):
-        with attempt:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(f"https://httpbin.org/status/{code}")
-            resp.raise_for_status()
-
-    return resp
-```
-<!-- example-end -->
-
-Both `retry()` and `retry_context()` take the following arguments (unless stated otherwise, **all time-based arguments are floats of seconds or [`datetime.timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta)s**):
-
-**on**: An Exception or a tuple of Exceptions on which the decorated callable will be retried.
-There is no default – you _must_ pass this explicitly.
-
-**attempts**: Maximum number of attempts (default: `10`).
-
-**timeout**: Maximum time for all retries.
-Can be combined with *attempts* (default: `45`).
-
-**wait_initial**: Minimum first backoff before first retry (default: `0.1`).
-
-**wait_max**: Maximum backoff time between retries (default: `5`).
-
-**wait_jitter**: Maximum _jitter_ that is added to retry back-off delays (the actual jitter added is a random number between 0 and *wait_jitter*) (default: `1`).
-
-**wait_exp_base**: The exponential base used to compute the retry backoff (default: `2`).
-
-The backoff for retry attempt number _attempt_ is computed as:
-
-```
-wait_initial * wait_exp_base ** (attempt - 1) + random(0, wait_jitter)
-```
-
-Since `x**0` is always 1, the first backoff is within the interval `[wait_initial,wait_initial+wait_jitter]`.
-Thus, with default values between 0.1 and 1.1 seconds.
-
----
-
-If all retries fail, the *last* exception is let through.
-
-
-### Global Settings
-
-There's two helpers for controlling and inspecting whether retrying is active:
-`stamina.is_active()` and `stamina.set_active()` (it's idempotent: you can call `set_active(True)` as many times as you want in a row).
-This is useful in tests.
-For example, here's a *pytest* fixture that automatically disables retries at the beginning of a test run:
-
-```python
-@pytest.fixture(autouse=True, scope="session")
-def deactivate_retries():
-    stamina.set_active(False)
-```
+- [**PyPI**](https://pypi.org/project/stamina/)
+- [**Source Code**](https://github.com/hynek/stamina)
+- [**Documentation**](https://py-stamina.readthedocs.io/)
+- [**Changelog**](https://github.com/hynek/stamina/blob/main/CHANGELOG.md)
 
 
 ## License

docs/api.rst

@@ -0,0 +1,14 @@
+API Reference
+=============
+
+.. module:: stamina
+
+.. autofunction:: retry
+.. autofunction:: retry_context
+
+
+Configuration
+-------------
+
+.. autofunction:: set_active
+.. autofunction:: is_active

docs/changelog.md

@@ -0,0 +1,2 @@
+```{include} ../CHANGELOG.md
+```

docs/conf.py

@@ -0,0 +1,100 @@
+# SPDX-FileCopyrightText: 2022 Hynek Schlawack <[email protected]>
+#
+# SPDX-License-Identifier: MIT
+
+from importlib import metadata
+
+
+# We want an image in the README and include the README in the docs.
+suppress_warnings = ["image.nonlocal_uri"]
+
+
+# -- General configuration ----------------------------------------------------
+
+extensions = [
+    "myst_parser",
+    "notfound.extension",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autodoc.typehints",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+]
+
+myst_enable_extensions = [
+    "colon_fence",
+    "smartquotes",
+    "deflist",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix of source filenames.
+source_suffix = [".rst", ".md"]
+
+# The master toctree document.
+master_doc = "index"
+
+# General information about the project.
+project = "stamina"
+author = "Hynek Schlawack"
+copyright = f"2022, { author }"
+
+
+# The full version, including alpha/beta/rc tags.
+release = metadata.version("stamina")
+# The short X.Y version.
+version = release.rsplit(".", 1)[0]
+
+if "dev" in release:
+    release = version = "UNRELEASED"
+
+exclude_patterns = ["_build"]
+
+nitpick_ignore = []
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+# add_module_names = True
+
+# Move type hints into the description block, instead of the func definition.
+autodoc_typehints = "description"
+autodoc_typehints_description_target = "documented"
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = "furo"
+html_theme_options = {
+    "source_branch": "main",
+    "source_directory": "docs/",
+}
+html_static_path = []
+
+htmlhelp_basename = "staminadoc"
+
+_descr = "Production-grade retries made easy for Python."
+_title = "stamina"
+rst_epilog = f"""\
+.. meta::
+    :property=og:type: website
+    :property=og:site_name: { _title }
+    :property=og:description: { _descr }
+    :property=og:author: Hynek Schlawack
+    :twitter:title: { _title }
+    :twitter:creator: @hynek
+"""
+
+# GitHub has rate limits
+linkcheck_ignore = [
+    r"https://github.com/.*/(issues|pull|compare)/\d+",
+    r"https://twitter.com/.*",
+]
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}