docs: fix CLI docs generator and OpenAPI reference rendering#157
Merged
docs: fix CLI docs generator and OpenAPI reference rendering#157
Conversation
The CLI docs generator emitted `{"page": "/path", "title": "..."}` entries
inside `pages` arrays, but Mintlify's docs.json schema only accepts strings
or `{"group", "pages"}` nested groups — sidebar labels must come from each
MDX's frontmatter `title`.
- Generate subcommand MDX with `title: "parent sub"` (e.g. `cvms list`).
- Emit plain string paths inside subcommand groups.
- Normalize legacy `{page, title}` objects back to strings on re-run, and
guard `processPages` against re-nesting a group inside itself.
- Regenerate docs.json and all CLI MDX pages.
Rendering fix:
- Move `openapi` reference from docs.json root into the "Phala Cloud API"
group. Root-level field is ignored by Mintlify, causing all
`METHOD /path` entries to 404.
Schema trim (scripts/export_openapi.py in the teehouse repo):
- Add `servers: [{"url": "https://cloud-api.phala.com"}]` so code
samples no longer show `api.example.com`.
- Exclude Authentication, Billing, Workspace, Profiles, Usage, Tokens,
and GPUs tags from the public schema.
- Drop operations marked `deprecated: true`.
- Remove `x-mint.href` extension — absolute URLs break local dev links.
Keep: Apps, CVMs, Attestations, KMS, SSH Keys, Instance Types, Webhooks
(102 operations across 88 paths).
docs.json sidebar is synced to match openapi.json exactly (no broken
or hidden entries).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs.jsonso endpoint pages render correctly.openapi.jsonto cover only the public API surface.Test plan
docs.jsonvalidation).mintlify broken-linksreports no new broken links.mintlify devthat OpenAPI endpoint pages render with the correct server URL and that CLI subcommand pages show the intended titles.