docs: implement publishing pipeline (#617)

[planetf1]

docs: implement publishing pipeline

Type of PR

• Bug Fix
• New Feature
• Documentation
• Other

Description

• Link to Issue: Fixes docs: implement publishing pipeline #617

Fixes #617

Draft — will be updated once PRs #601 and #611 merge.

This PR cannot be fully tested until those two land, as they provide the
static docs content and the API docs build tooling respectively.

Implements Option B from #617: dedicated orphan deployment branches for
Mintlify. CI builds and validates documentation, then pushes the combined
output (static guides + generated API reference) to docs/staging (from
main) or docs/production (from releases).

Changes

• .github/workflows/docs-publish.yml — new unified workflow replacing
  docs-autogen-pr.yml. Triggers on push to main, release published, PRs
  (validation only), and workflow_dispatch (with force_publish override
  for testing). Validation is soft-fail by default; strict_validation
  input can be enabled when ready.
• .github/workflows/docs-autogen-pr.yml — deleted (replaced by above).
• .pre-commit-config.yaml — adds two informational hooks: MDX
  validation when doc files change, docstring quality audit when Python
  source changes. Both skip gracefully if generated docs aren't present.
• docs/PUBLISHING.md — documents the publishing architecture, branch
  strategy, local development workflow, and Mintlify configuration.
• .gitignore — adds entries for generated docs/docs/api/ and
  docs/docs/api-reference.mdx.

Dependencies

Requires these PRs to merge first:

• docs: complete developer documentation rewrite (#480) #601 — static docs rewrite (provides content + markdownlint config)
• docs: Docs/api pipeline improvements #611 — API docs pipeline (provides build.py, validate.py,
  audit_coverage.py, poe tasks, and generated MDX output)

Nice to have but not blocking:

• docs: improve docstrings for API reference (#612) #614 — improved docstrings
• fix: add missing type annotations to public API functions #619 — type annotations

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code as added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Testing plan (post-merge of dependencies):

• Run workflow_dispatch with force_publish=true and a test target branch
• Verify Mintlify picks up content from the deployment branch
• Validate markdownlint and coverage audit pass in CI
• Flip strict_validation once remaining issues are resolved

[github-actions]

The PR description has been updated. Please fill out the template for your PR to be reviewed.

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert|release)(?:\(.+\))?:

[planetf1]

Not ready for review yet. Opening to share the idea -- we need the mandatory core PRs merged first

[planetf1]

Recreating PR from upstream branch to enable deploy testing. See replacement PR.

[planetf1]

Replaced by #646 (same changes, pushed to upstream branch to enable deploy testing).