The problem
Mintlify is currently configured with no build step — it reads files directly from a branch (main for prod, update-docs for preview). This works perfectly for the hand-authored static content in PR #601.
PR #611 introduces a generated API reference that cannot follow the same model. The docs are built from Python source by tooling/docs-autogen/ and must be regenerated on every release. They are excluded from git tracking (.gitignore) precisely so they are never hand-edited or accidentally committed.
The tension: Mintlify will never see the API docs unless we either add a build step or commit the generated output somewhere it can read from.
Options
A — Commit generated output on each release (minimal change)
Keep docs-autogen-pr.yml: CI generates the API docs on each tag and commits them via a PR. Mintlify needs no config change. Generated files re-enter the repo on every release — requires the .gitignore approach in #611 to be revisited (or replaced with a convention).
B — Dedicated publish branch (clean, more work)
A docs-publish branch is never directly committed to. On each release, CI combines the static content from main with freshly generated API docs and pushes the result to docs-publish. Mintlify is reconfigured to read from that branch. main stays clean. Requires a Mintlify config change and a pipeline step to carry the static content across.
C — Mintlify custom build step (investigate)
If Mintlify supports running an arbitrary build command, the pipeline could run there with no branch changes needed. Needs investigation.
When to decide
After PR #601 and PR #611 have both merged, since the Mintlify branch config and the .gitignore boundary are established by those PRs respectively. Option B is the cleanest long-term answer; Option A is lowest friction to unblock publishing.
The problem
Mintlify is currently configured with no build step — it reads files directly from a branch (
mainfor prod,update-docsfor preview). This works perfectly for the hand-authored static content in PR #601.PR #611 introduces a generated API reference that cannot follow the same model. The docs are built from Python source by
tooling/docs-autogen/and must be regenerated on every release. They are excluded from git tracking (.gitignore) precisely so they are never hand-edited or accidentally committed.The tension: Mintlify will never see the API docs unless we either add a build step or commit the generated output somewhere it can read from.
Options
A — Commit generated output on each release (minimal change)
Keep
docs-autogen-pr.yml: CI generates the API docs on each tag and commits them via a PR. Mintlify needs no config change. Generated files re-enter the repo on every release — requires the.gitignoreapproach in #611 to be revisited (or replaced with a convention).B — Dedicated publish branch (clean, more work)
A
docs-publishbranch is never directly committed to. On each release, CI combines the static content frommainwith freshly generated API docs and pushes the result todocs-publish. Mintlify is reconfigured to read from that branch.mainstays clean. Requires a Mintlify config change and a pipeline step to carry the static content across.C — Mintlify custom build step (investigate)
If Mintlify supports running an arbitrary build command, the pipeline could run there with no branch changes needed. Needs investigation.
When to decide
After PR #601 and PR #611 have both merged, since the Mintlify branch config and the
.gitignoreboundary are established by those PRs respectively. Option B is the cleanest long-term answer; Option A is lowest friction to unblock publishing.