Add the API reference site, built on every PR and deployed to GitHub Pages on release

[zeevmoney]

Linear issues

• PER-16775: API reference site for permit-python at https://permitio.github.io/permit-python/ (PR 2 of 3)
• PER-16336: SDK upgrade guide; section 15 sets the rules this site follows

Stacked on #151 (docstring fixes), which is stacked on #150 and #144.

Why

permit-python has no API reference of its own; docs.permit.io carries the guides. This adds a reference-only site generated from the SDK's docstrings and type annotations. It shows the signatures a type checker sees, links to docs.permit.io for guides and to the REST API reference for full model schemas, builds on every PR, fails on any docs warning or broken link, and deploys only on release or by hand. It has one version until a second major exists.

What changed

Site (mkdocs.yml, docs/)

• Built with Zensical 0.0.65 from an MkDocs-format mkdocs.yml (Material theme), with mkdocstrings 1.0.6, mkdocstrings-python 2.0.9 on griffelib 2.3.0, and pymdown-extensions 12.1 (highlight, magiclink, snippets, superfences). Each is pinned exactly in a new docs dependency group, and uv.lock is resolved under the repo's 7-day cooldown. griffelib is also pinned in dev, at the same version, for mypy and the offline tests.
• Pages: Home (includes README.md), "Upgrading to 3.0" (includes MIGRATION.md), "Async or blocking client", and 29 reference pages: the two clients, configuration, exceptions, enforcement types, an index and one page per permit.api API (the async class, then its blocking twin), the deprecated methods, the PDP API, Elements, and Models. The models page lists the 84 models that public methods take or return, and links to https://api.permit.io/scalar for the rest. A navigation entry links every page to docs.permit.io.

Griffe extension (scripts/docs_griffe_extension.py)

• Where a name is bound under if TYPE_CHECKING: (or <module>.TYPE_CHECKING) and rebound at runtime by a class or an assignment, the page shows the type checker's binding, matched by full path. So the blocking API classes, SyncElementsApi and SyncEnforcer come from permit/_sync_types.pyi, and the PDP SyncRoleAssignmentsApi gets the PDP stub class, not the REST one. Runtime imports are kept.
• Labels functions and classes decorated with the SDK's deprecated or a PEP 702 deprecated, and appends the decorator's message. Stub methods take the deprecation of the async method they are generated from.
• Shows the return type of a @contextmanager function as contextlib.AbstractContextManager[<yielded type>] (Permit.wait_for_sync()). Its Yields section still names the yielded type.
• Uses a pydantic field's Field(description=...) as its docstring and its default as its value.
• tests/test_docs_griffe_extension.py: 25 offline tests (0.3 s), including the PDP/REST full-path regression and a check that the models page lists exactly the models of public signatures.

Build gate (.github/scripts/check_docs_build.py, stdlib only)

• Runs zensical build --strict --clean with its own interpreter, under a root logging handler, so every record of level WARNING and up prints as LEVEL:logger:message. It streams the build log as it runs.
• Exit 1 when the build fails, or its log has a Zensical diagnostic, a logged warning or error, a Python warning or a traceback (the verdict lists each traceback's exception first). Also exit 1 when a relative href or src in the built site reaches no page, file or anchor (404.html and absolute links are skipped). That covers links in docstrings and in the included README.md and MIGRATION.md, which Zensical's own check does not see.
• Exit 2 when the build did not run to the end: zensical is not installed for the interpreter, the command could not start, a signal stopped it, or it wrote no new site/index.html.
• .github/scripts/test_check_docs_build.py: 45 tests, run in the Audit Script Tests job.

CI and deploy

• test.yml: a new docs job (15-minute timeout, contents: read, SHA-pinned actions, persist-credentials: false) builds the site through the gate. ci.needs includes it, and EXPECTED_JOBS is 11.
• .github/workflows/docs-deploy.yml (Deploy Docs) runs on release: released and workflow_dispatch. Its build job uses the same uv setup, install step and build step as CI (tests keep them identical), with no cache, then actions/configure-pages v6.0.0 and actions/upload-pages-artifact v5.0.0. Its deploy job has only pages: write and id-token: write, runs in environment: github-pages and uses actions/deploy-pages v5.0.1. The workflow sets concurrency: { group: pages, cancel-in-progress: false }, top-level permissions: contents: read and 15-minute timeouts. Each action is pinned to its release commit SHA.
• Dependabot: a docs-tools group (zensical, mkdocstrings*, griffe*, pymdown-extensions), listed before minor-and-patch.
• python-sdk-publish.yml is not changed.

Docs

• CONTRIBUTING.md: a new section, "The API reference site". It covers building and previewing the site, the gate and its exit codes, adding a page, an API class or a model, and when and how the site deploys.
• README.md: one sentence linking to the site.
• MIGRATION.md: the two links to the migration skill are now absolute GitHub URLs, so they work on the site and on PyPI.

Behaviour changes

• No change to SDK code or docstrings.
• CI needs the new docs job, so a PR fails CI when the site build fails, logs a warning, or has a broken link or anchor.
• Publishing a release that is not a prerelease, or changing a prerelease to a release, deploys the site to GitHub Pages. A prerelease does not deploy. Deploy Docs can also be run by hand.
• Dependabot opens docs tool bumps in their own group.

How it was tested

• Local build through the gate: exit 0, no warnings, 34 HTML pages in about 4.3 s, about 5,800 relative links checked.
• The gate on the real build, with planted faults:
  • an Args: entry for a missing parameter: exit 1, listing the 2 Griffe lines;
  • a broken link in a docstring and a wrong anchor in MIGRATION.md: exit 1, each listed with its page;
  • a broken link in docs/: exit 1 (Zensical diagnostic);
  • a warning from a plain logging logger in the extension: exit 1;
  • an unreadable deprecation message, and a missing snippet: exit 1, each listing the exception first;
  • site_dir pointed at another directory: exit 2;
  • zensical not importable: exit 2.
• Checks on the built HTML:
  • On all 20 permit.api pages, the blocking class has methods, none labelled async and none with Coroutine or Awaitable types, and the async class's methods are labelled async.
  • The PDP SyncRoleAssignmentsApi shows only list(), with resource_instance_key.
  • RoleRead.name shows "The name of the role", and no Field( call appears on any page.
  • DeprecatedApi.get_user, SyncDeprecatedApi.get_user, TenantsApi.add_user, SyncTenantsApi.add_user and PermitException carry the deprecated label and message.
  • No raw ``` fence is left, and the examples are highlighted.
  • wait_for_sync() returns AbstractContextManager[Self] on both client pages, and its See Also URL is a link.
  • The same checks fail on a site built with the TYPE_CHECKING replacement turned off (21 misses).
• Mutation checks: 35 deliberate breaks of the gate, the extension and the workflows each made at least one test fail.
• uv run pre-commit run --all-files: pass (ruff, mypy, typos, uv lock --check).
• mypy, pydantic 2 and pydantic 1 lanes: no issues in 127 files.
• Offline suite (pytest -m "not e2e"): 1943 passed, 3 skipped, in each of the pydantic 2 and pydantic 1 lanes.
• .github/scripts tests (including test_ci_checks.py and test_check_docs_build.py): 318 passed. Migration skill tests: 86 passed, 1 skipped.
• actionlint: clean. zizmor 1.30.1, offline and online: no findings.
• Not yet run on GitHub: the docs job and Deploy Docs.

Owner actions before merge

• Prereleases: Deploy Docs runs on released, so a prerelease does not deploy and a prerelease later changed to a release does. To deploy prereleases as well, change it to types: [published].
• The github-pages environment accepts deploys from main and v* tags only, so tag the release v3.1.0, as 3.0.0 was tagged v3.0.0. A tag without the v publishes to PyPI but cannot deploy the site.
• Today's ruleset lists six job checks, not Docs, so the docs build blocks merges only once the ruleset requires CI alone (the owner action in Add an aggregate CI check and run every PR job from test.yml #150).
• After merge: run Deploy Docs from main (or wait for the next release) for the first deploy. Check that configure-pages works with pages: read and that the environment protection lets deploy-pages through.

🤖 Generated with Claude Code

[linear-code]

PER-16775

[github-actions]

Dependency Security Audit

Scanned: pyproject.toml dependencies + dev group, resolved at Python 3.10 (the current resolution, and the lowest versions the published specs permit under each pydantic major)

✅ No known vulnerabilities found.

Both the resolved dependency set and the lowest versions the published specs permit are clean at HIGH and CRITICAL.