fix: render Click \b verbatim blocks in CLI reference docs (#866)#867
Merged
planetf1 merged 4 commits intogenerative-computing:mainfrom Apr 16, 2026
Merged
fix: render Click \b verbatim blocks in CLI reference docs (#866)#867planetf1 merged 4 commits intogenerative-computing:mainfrom
planetf1 merged 4 commits intogenerative-computing:mainfrom
Conversation
…e-computing#866) The docs generator was silently dropping \b-delimited sections (Modes, Best practices, Detection notes, Rewrites) from m fix async and m fix genslots. These blocks were buried inside the Raises section by the docstring parser and never rendered, causing a fidelity gap with --help output. Adds _extract_verbatim_blocks() to split on \x08 directly from the raw help text, independent of the section parser. Three new tests verify the extraction logic and that the affected content now appears in the generated reference page.
Contributor
|
The PR description has been updated. Please fill out the template for your PR to be reviewed. |
Best practices, Detection notes and Rewrites sections in \b blocks are bullet lists and should render as markdown, not monospace code. Modes retains a code fence as it uses columnar alignment. Continuation lines wrapped across multiple source lines are joined back into their parent bullet.
Click-style two-column aligned blocks (e.g. Modes in m fix async) were rendered as code fences. The generator now detects the name + 2-space + description pattern and emits a markdown table, preserving the original terminal-aligned docstring format while rendering cleanly in HTML docs.
Table cells render in a smaller font than body text in Mintlify, creating inconsistency with bullet-list blocks. Render two-column \b blocks as `- **\`name\`** — description` bullets instead: consistent font, no invented column headers.
Contributor
Author
|
AFTER merge this will be available at https://ibm-llm-runtime-aaf3a78b.mintlify.app/ for verification. It will get to https://mellea.ai when the next release is made. |
serjikibm
approved these changes
Apr 16, 2026
Collaborator
serjikibm
left a comment
serjikibm
left a comment
There was a problem hiding this comment.
LGTM, we can further verify on the staging url
Contributor
Author
Thanks for the review - I presume you do not have write access? cc: @psschwei perhaps you could check you're ok with the change |
AngeloDanducci
approved these changes
Apr 16, 2026
| continue | ||
| # Detect a new entry: leading whitespace, a name (no spaces), then 2+ | ||
| # spaces, then description text — all starting before the desc column. | ||
| m = re.match(r"^(\s+)(\S+)(\s{2,})(\S.*)", raw) |
Contributor
There was a problem hiding this comment.
For a moment I though this should maybe be \s* instead of \s+ but this matches the description so as long as the format is consistent should be fine.
Merged
via the queue into
generative-computing:main
with commit Apr 16, 2026
687871e
16 checks passed
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
3 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.
fix: render Click \b verbatim blocks in CLI reference docs
Type of PR
Description
The CLI reference docs generator was silently dropping
\b-delimitedsections from
m fix asyncandm fix genslots. These blocks —Modes, Best practices, Detection notes, Rewrites — are visible in
--helpbut were buried afterRaises:in the docstrings, which thesection parser assigns to
sections["Raises"], a section that is neverrendered.
Fix adds
_extract_verbatim_blocks()which splits the raw help text on\x08directly, independent of the section parser. Blocks are renderedafter the options table with format chosen to match their content:
as markdown bullets, with wrapped continuation lines rejoined.
(
- **\name`** — description`) to preserve the name/descriptionstructure at consistent font size.
PDF -> CLI Reference - Mellea.pdf
Testing
Attribution