Skip to content

ci: add -split flag to gen-docs to support cloud CLI extension docs#980

Open
lennessyy wants to merge 2 commits intomainfrom
docs/gen-docs-split-flag
Open

ci: add -split flag to gen-docs to support cloud CLI extension docs#980
lennessyy wants to merge 2 commits intomainfrom
docs/gen-docs-split-flag

Conversation

@lennessyy
Copy link
Copy Markdown
Contributor

@lennessyy lennessyy commented Apr 14, 2026

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-docs with multiple -input flags to generate docs from YAML command definitions.

The problem is that gen-docs currently produces one file per top-level command. Since all cloud commands share the cloud root, they'd all land in a single cloud.mdx file (~2800 lines), which is too large to be useful.

This PR adds a -split flag that tells gen-docs to output a command's subcommands as separate files in a subdirectory. The documentation repo's workflow will pass -split cloud to produce individual pages:

cloud/namespace.mdx  (1148 lines)
cloud/account.mdx    (318 lines)
cloud/user-group.mdx (417 lines)
cloud/user.mdx       (262 lines)
cloud/apikey.mdx     (253 lines)
cloud/nexus.mdx      (212 lines)
cloud/connectivity.mdx (144 lines)
cloud/login.mdx
cloud/logout.mdx
cloud/whoami.mdx

No changes are needed in the cloud-cli repo. The split is controlled entirely by the documentation workflow:

go run ./cmd/gen-docs \
  -input internal/temporalcli/commands.yaml \
  -input path/to/cloud-cli/commands.yml \
  -split cloud \
  -output dist/docs

Also fixes the encodeJSONExample regex to catch standalone JSON objects in single quotes (e.g., '{"key":"value"}'), which caused MDX rendering errors.

Test plan

  • CLI-only generation produces identical flat output (no regressions)
  • -split cloud produces cloud/ subdirectory with correct file splits
  • Generated content (frontmatter, headings, flag tables, global flags) renders correctly
  • JSON-in-tables MDX rendering fix works
  • CI checks pass

🤖 Generated with Claude Code

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>
@lennessyy lennessyy requested a review from a team as a code owner April 14, 2026 00:46
@lennessyy lennessyy changed the title feat: add -split flag to gen-docs for subdirectory output feat: add -split flag to gen-docs to support cloud CLI extension docs Apr 14, 2026
@lennessyy lennessyy changed the title feat: add -split flag to gen-docs to support cloud CLI extension docs docs: add -split flag to gen-docs to support cloud CLI extension docs Apr 14, 2026
@lennessyy lennessyy changed the title docs: add -split flag to gen-docs to support cloud CLI extension docs ci: add -split flag to gen-docs to support cloud CLI extension docs Apr 14, 2026
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant