feat(docs): Publish pdoc-generated API reference to GitHub Pages

[gjtorikian]

Summary

• Add a Publish API Docs GitHub Actions workflow that runs on tag pushes (and manual dispatch), generates the site with pdoc, and deploys it to GitHub Pages so SDK docs stay in lockstep with releases.
• Upload the artifact via actions/upload-artifact (manual tar step + github-pages artifact name) instead of actions/upload-pages-artifact, which Socket flagged for an input-argument taint flow — matches the workos-dotnet (Make events parameter required for list_events #251) and workos-kotlin fixes.
• Add scripts/docs.sh (build) and scripts/docs-serve.sh (local preview, with --live for pdoc's hot-reload server) plus a docs dependency group with pdoc and pydoc-markdown.
• Emit llms.txt alongside the HTML so LLM coding assistants can discover the canonical reference without crawling HTML; version is read from pyproject.toml at build time.
• Ignore the local docs/_site/ build output.

Test plan

• uv sync --locked --dev installs the new docs group cleanly
• ./scripts/docs.sh produces docs/_site/{index.html,index.md,llms.txt,workos.html,workos.md}
• ./scripts/docs-serve.sh serves the built site at http://localhost:4000
• ./scripts/docs-serve.sh --live starts pdoc's live-reload server
• llms.txt reflects the current version from pyproject.toml
• Trigger the workflow via workflow_dispatch once merged and confirm the Pages deploy succeeds

[greptile-apps]

Greptile Summary

This PR adds a GitHub Actions workflow to publish pdoc-generated API reference docs to GitHub Pages on tag pushes, along with local build and preview scripts, a docs dependency group, and an llms.txt discovery file.

• docs.yml: Builds docs, archives with tar, and deploys to Pages using pinned-SHA actions to avoid the upload-pages-artifact input-taint issue flagged by Socket.
• scripts/docs.sh: Runs pdoc and pydoc-markdown to produce HTML and Markdown output, then writes llms.txt with the version read from pyproject.toml — but uses tomllib, which is Python 3.11+ only, against a >=3.10 project constraint.
• scripts/docs-serve.sh: Provides a local --live hot-reload mode via pdoc or a static http.server fallback.

Confidence Score: 4/5

Safe to merge once the tomllib compatibility gap is addressed; all other changes are additive and low-risk.

The docs.sh script calls import tomllib, only available in Python 3.11+, while the project supports Python >=3.10. Running under Python 3.10 would fail with ModuleNotFoundError at the version-extraction step, causing llms.txt to never be written and the build job to exit non-zero.

scripts/docs.sh — the tomllib import needs a 3.10-compatible fallback.

Important Files Changed

Filename	Overview
.github/workflows/docs.yml	New GitHub Actions workflow to build and deploy pdoc-generated docs to GitHub Pages; uses pinned SHAs, manual tar workaround for Socket-flagged upload-pages-artifact, and splits build/deploy into separate jobs.
scripts/docs.sh	Build script for pdoc HTML + pydoc-markdown Markdown output; uses tomllib (Python 3.11+ stdlib) to extract version, which will fail on Python 3.10 despite the project supporting >=3.10.
scripts/docs-serve.sh	Local preview helper that either starts pdoc's live-reload server (--live) or serves the pre-built site with Python's http.server; straightforward with no issues.
pyproject.toml	Adds a docs dependency group with pdoc>=14 and pydoc-markdown>=4; no issues.
.gitignore	Adds docs/_site/ to .gitignore to exclude the local build output; correct and complete.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([push tag v* OR workflow_dispatch]) --> B[build job]
    B --> C[actions/checkout]
    C --> D[astral-sh/setup-uv]
    D --> E[actions/setup-python reads pyproject.toml]
    E --> F[./scripts/docs.sh]
    F --> F1[pdoc docs/_site/]
    F1 --> F2[pydoc-markdown workos.md/index.md]
    F2 --> F3[tomllib llms.txt with version]
    F3 --> G[actions/configure-pages]
    G --> H[tar archive RUNNER_TEMP/artifact.tar]
    H --> I[actions/upload-artifact name: github-pages]
    I --> J[deploy job]
    J --> K[actions/deploy-pages]
    K --> L([GitHub Pages live URL])

Loading

_{Reviews (1): Last reviewed commit: "feat(docs): Generate llms.txt for the pu..." | Re-trigger Greptile}

[greptile-apps]

tomllib was added to Python's standard library in 3.11, but this project requires python >= 3.10. Running this script under Python 3.10 will fail with ModuleNotFoundError: No module named 'tomllib'. In CI the setup-python step may resolve to a newer interpreter, but locally — or if uv selects Python 3.10 — the build breaks at the version-extraction step.

Suggested change

	version=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
	version=$(uv run python -c "
	try:
	import tomllib
	except ImportError:
	try:
	import tomli as tomllib
	except ImportError:
	import sys, re
	data = open('pyproject.toml').read()
	m = re.search(r'^version\s*=\s*\"([^\"]+)\"', data, re.MULTILINE)
	if not m:
	sys.exit('Cannot determine version from pyproject.toml')
	print(m.group(1))
	raise SystemExit(0)
	print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])
	")

[greptile-apps]

The uv run calls omit --locked, so uv may resolve and install package versions that differ from what is pinned in uv.lock. Adding --locked ensures the docs build is reproducible and consistent between local runs and CI.

Suggested change

	uv run --group docs pdoc workos -o docs/_site --docformat google
	if [ ! -f docs/_site/index.html ] && [ -f docs/_site/workos.html ]; then
	cp docs/_site/workos.html docs/_site/index.html
	fi
	uv run --group docs pydoc-markdown -p workos --render-toc > docs/_site/workos.md
	uv run --locked --group docs pdoc workos -o docs/_site --docformat google
	if [ ! -f docs/_site/index.html ] && [ -f docs/_site/workos.html ]; then
	cp docs/_site/workos.html docs/_site/index.html
	fi
	uv run --locked --group docs pydoc-markdown -p workos --render-toc > docs/_site/workos.md