ci: add -split flag to gen-docs to support cloud CLI extension docs#980
Open
ci: add -split flag to gen-docs to support cloud CLI extension docs#980
Conversation
Add a `-split` flag that specifies command names whose subcommands
should each get their own file in a subdirectory rather than all being
combined into a single file.
This is needed for the cloud CLI extension, which has ~130 commands
that would produce an unmanageably large single page. With `-split
cloud`, gen-docs produces cloud/namespace.mdx, cloud/user.mdx, etc.
Also fixes the encodeJSONExample regex to catch standalone JSON objects
in single quotes (e.g., '{"key":"value"}'), not just key=value patterns.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Leaf commands (e.g., cloud login) that have no subcommands no longer reference a nonexistent #global-flags anchor. Instead they render their description and options directly on the page. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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
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
The Temporal Cloud CLI extension needs auto-generated command reference documentation, just like the core CLI commands. The extension has ~130 commands across 10 top-level groups (namespace, user, apikey, account, etc.), and the documentation repo's workflow already uses
gen-docswith multiple-inputflags to generate docs from YAML command definitions.The problem is that
gen-docscurrently produces one file per top-level command. Since all cloud commands share thecloudroot, they'd all land in a singlecloud.mdxfile (~2800 lines), which is too large to be useful.This PR adds a
-splitflag that tellsgen-docsto output a command's subcommands as separate files in a subdirectory. The documentation repo's workflow will pass-split cloudto produce individual pages:No changes are needed in the cloud-cli repo. The split is controlled entirely by the documentation workflow:
Also fixes the
encodeJSONExampleregex to catch standalone JSON objects in single quotes (e.g.,'{"key":"value"}'), which caused MDX rendering errors.Test plan
-split cloudproducescloud/subdirectory with correct file splits🤖 Generated with Claude Code