fix(cli/docs): emit markdown-safe CLI reference (fenced examples, inline aliases)#1269
Open
ppiegaze wants to merge 1 commit into
Open
fix(cli/docs): emit markdown-safe CLI reference (fenced examples, inline aliases)#1269ppiegaze wants to merge 1 commit into
ppiegaze wants to merge 1 commit into
Conversation
ppiegaze
added a commit
to unionai/unionai-docs
that referenced
this pull request
Jun 29, 2026
…s + inline aliases) Replaces the hand-patched stopgap with a full regeneration using the fixed CLI doc generator (flyteorg/flyte-sdk#1269): all multi-name options render inline (no {{< multiline >}} raw HTML) and all command Examples are fenced ```bash blocks (no indentation-based code). Version pinned to 2.5.6 (the local SDK build reports a dev version). Durable once #1269 ships; until then the committed file is the correct shape.
ppiegaze
added a commit
to unionai/unionai-docs
that referenced
this pull request
Jun 29, 2026
…#1153) * docsy(v2): regenerate API reference 2.5.2 → 2.5.6 (maintenance regen) Regenerated flyte SDK + flyte-cli + plugin API reference from the 2.5.6 docstrings via 'make update-api-docs'. All 24 packages were stale at 2.5.2. No condition-API surface change between 2.5.2 and 2.5.6. * test(regen): drop angle brackets from connect-ssh example <name> to test Hugo raw-HTML build failure * fix(regen): fence indented CLI example blocks in flyte-cli.md The 2.5.6 'flyte connect'/'create api-key' help text emitted Examples as 4-space-indented blocks; inside {{< markdown >}} RenderString these render as prose, so the <name>/<base64-...> placeholders became raw HTML and (under --panicOnWarning) failed the Hugo build. Wrap the example commands in fenced ```bash blocks (dedented) so they render as code and the angle brackets are safe. * fix(regen): replace multiline shortcode with inline flags in plugin CLI table Root cause of the Hugo build failure: {{< multiline >}} emits <div>/<br/> raw HTML. Inside the {{< markdown >}} RenderString path (unsafe off, --panicOnWarning) that is a fatal 'Raw HTML omitted'. main has 0 such rows; the 2.5.6 'connect ssh' plugin command added 2 multi-alias flag rows inside a markdown block. Render the aliases inline as `--a` / `--b` instead (plain markdown, no raw HTML). * regen(cli): flyte-cli.md from markdown-safe generator (fenced examples + inline aliases) Replaces the hand-patched stopgap with a full regeneration using the fixed CLI doc generator (flyteorg/flyte-sdk#1269): all multi-name options render inline (no {{< multiline >}} raw HTML) and all command Examples are fenced ```bash blocks (no indentation-based code). Version pinned to 2.5.6 (the local SDK build reports a dev version). Durable once #1269 ships; until then the committed file is the correct shape.
…ine aliases)
The 'flyte gen docs' markdown output broke the Hugo docs build when a *plugin*
command (rendered inside a {{< markdown >}} variant block) had:
1) a multi-name/alias option — emitted via the {{< multiline >}} shortcode,
which produces raw <div>/<br/> HTML. Inside {{< markdown >}}.RenderString
(goldmark unsafe=false + --panicOnWarning) that is a fatal 'Raw HTML omitted'.
2) an 'Examples:' block — emitted as indentation-based code, which doesn't
survive RenderString and renders inconsistently.
Fixes:
- Render option aliases inline (`--a` `--b`) instead of {{< multiline >}}.
- Format command help via inspect.cleandoc (handles the first-line-on-quotes
docstring case) and wrap indented blocks in fenced ```bash code blocks.
Surfaced regenerating the v2 API reference for flyte 2.5.6 (new 'flyte connect'
plugin command); see unionai-docs#1153.
Signed-off-by: ppiegaze <1153481+ppiegaze@users.noreply.github.com>
ppiegaze
force-pushed
the
docsy/cli-doc-gen-markdown-safe
branch
from
be6c030 to
04f6e56
Compare
cosmicBboy
approved these changes
Jun 29, 2026
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
2 participants
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.
Problem
flyte gen docs --type markdownproduces the CLI reference page (flyte-cli.md) for the docs site. For plugin commands it wraps each command in a{{< variant >}}{{< markdown >}}block (variant-gating). Two constructs it emits then break the Hugo build inside that block:{{< multiline >}}shortcode (_gen.py), which outputs raw<div>/<br/>HTML. Inside{{< markdown >}}'s.Page.RenderString(goldmarkunsafe=false, build run with--panicOnWarning) that is a fatal "Raw HTML omitted".Examples:blocks come through as indentation-based code, which doesn't surviveRenderStringand renders inconsistently.Core commands sit in plain page markdown (shortcode HTML passes straight through, never re-rendered), so this only bites plugin commands — and only surfaced now because flyte 2.5.6's new
flyte connectplugin command is the first with multi-alias options + an Examples block. It took down the entireBuild and deploy docsjob (see unionai-docs#1153).Fix (
src/flyte/cli/_gen.py)`--a` `--b`instead of the{{< multiline >}}shortcode — works in both plain and{{< markdown >}}contexts, no raw HTML._format_command_help()formats command help withinspect.cleandoc(handles the first-line-on-"""docstring case thattextwrap.dedentcan't) and wraps indented blocks in fenced ```bash code blocks instead of relying on indentation.Docs-pipeline plumbing only; no runtime/behavior change. Verified the formatter output on the
connect sshhelp (prose dedented, examples fenced,<…>placeholders now safe inside the fence).🤖 Generated with Claude Code