docs: add Python API reference artifact pipeline

[cesarenaldi]

Summary

• add a Sphinx JSON proof of concept for the Python SDK clients and representative public models, enums, types, and values
• allow manual generation of a commit-specific ZIP artifact without publishing a package or release
• attach an immutable, versioned ZIP to future GitHub Releases after successful PyPI publication
• document the local build and Mintlify integration model

Scope

This intentionally validates representative API shapes before expanding to the complete supported public surface. The generated output covers sync and async clients, create(), get_balance_allowance(), Pydantic fields, typed dataclasses, enums, type markers, constants, functions, cross-links, and search metadata.

The next step is to generate the artifact manually, load it into a Mintlify preview, and evaluate the rendered information architecture before expanding coverage.

Verification

• make api-reference
• ZIP integrity check
• make check (1976 passed, 184 deselected)
• uv build
• actionlint .github/workflows/api-reference.yml .github/workflows/release-please.yml
• uv lock --check

---

Note

Low Risk
Changes are limited to documentation sources, dev dependencies, and release/CI automation; they do not alter SDK runtime behavior. The release job only writes GitHub Release assets when a normal release is created.

Overview
Adds a Sphinx JSON build that packages a Mintlify-compatible ZIP of the Python SDK reference (clients, sample models/types/values) from installed package docstrings, with warnings treated as build failures via make api-reference.

CI: New manually dispatched API Reference workflow uploads a commit-SHA artifact. The release workflow now exposes tag_name and, after a successful PyPI publish on a new release, builds the same ZIP and attaches polymarket-client-<version>-sphinx.zip to the GitHub Release.

Tooling: docs dependency group (sphinx), lockfile updates, and README/docs under docs/reference describing local builds and Mintlify sdk config. Coverage is explicitly a representative POC, not the full public API surface yet.

^{Reviewed by Cursor Bugbot for commit 19ba7be. Bugbot is set up for automated code reviews on this repo. Configure here.}