feat: Write command help text as Markdown - #500
Draft
danielvallance wants to merge 1 commit into
Draft
danielvallance wants to merge 1 commit into
danielvallance wants to merge 1 commit into
Conversation
There was a problem hiding this comment.
馃煛 Changes recommended
The user-facing Markdown help behavior lacks required end-to-end integration coverage.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Converts CLI help text to Markdown for consistent terminal, MDX, and man-page rendering, relying on unikraft-cloud/x#462.
Changes:
- Rewrites API and root help as Markdown.
- Adds MDX escaping and man-page heading demotion.
- Adds generator tests and updated golden outputs.
File summaries
| File | Description |
|---|---|
internal/cmd/api.go |
Converts API help to Markdown. |
internal/cmd/root.go |
Wraps the root banner in a code block. |
tools/gendocs/mdx.go |
Preserves Markdown descriptions and adds Usage headings. |
tools/gendocs/mdx_escape.go |
Extracts prose-line transformation logic. |
tools/gendocs/man.go |
Demotes description headings for md2man. |
tools/gendocs/detail.go |
Implements heading detection and demotion. |
tools/gendocs/detail_test.go |
Tests heading transformations. |
tools/gendocs/generate_test.go |
Adds generator golden tests. |
tools/gendocs/testdata/api.mdx.golden |
Captures expected MDX output. |
tools/gendocs/testdata/api.man.golden |
Captures expected man source. |
cmd/unikraft/testdata/TestHelp/api |
Updates API help output. |
cmd/unikraft/testdata/TestHelp/auth |
Updates reflowed profile help. |
cmd/unikraft/testdata/TestHelp/instances |
Updates rendered instance help. |
go.mod |
Updates kingkong and test dependencies. |
go.sum |
Updates dependency checksums. |
Review details
- Files reviewed: 14/15 changed files
- Comments generated: 1
- Review effort level: Balanced
馃挕 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| EXAMPLES | ||
|
|
||
| The examples below demonstrate many of the syntax forms described above.` | ||
| return heredoc.Docf(` |
danielvallance
force-pushed
the
danielvallance/unikraft_api_docs_render
branch
2 times, most recently
from
September 11, 2026 11:48
d3decd8 to
d7f9dd8
Compare
The api description was written for the terminal, with ALL-CAPS headings and indented tables. Both generators emitted it verbatim, so the docs page showed pseudo-headings and the man page reflowed the aligned columns into ragged text. It is now Markdown: kingkong renders it for the terminal, the docs pass it through, and man generation demotes the headings for md2man. gendocs gains golden coverage, and one example which documented the wrong key order is corrected. Closes: GTM-813 Signed-off-by: Daniel Vallance <daniel@unikraft.com>
danielvallance
force-pushed
the
danielvallance/unikraft_api_docs_render
branch
from
September 11, 2026 11:49
d7f9dd8 to
326b89d
Compare
danielvallance
marked this pull request as ready for review
September 11, 2026 12:22
There was a problem hiding this comment.
馃數 Needs a closer look
The user-facing help rendering lacks required integration-suite coverage.
Review details
Suppressed comments (1)
internal/cmd/api.go:250
- This changes the user-facing
unikraft api --helpoutput, but there is no corresponding case in the integration suite; the updated help and generator goldens run only under the offline golden workflow. Please add integration coverage that verifiesunikraft api --helpexits successfully, renders the Markdown headings without literal##markers, preserves the aligned request-syntax blocks, and emits no ANSI escapes.
return heredoc.Docf(`
- Files reviewed: 14/15 changed files
- Comments generated: 0 new
- Review effort level: Balanced
Contributor
Author
|
danielvallance
marked this pull request as draft
September 11, 2026 12:28
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.
The api description was written for the terminal, with ALL-CAPS headings and indented tables. Both generators emitted it verbatim, so the docs page showed pseudo-headings and the man page reflowed the aligned columns into ragged text.
It is now Markdown: kingkong renders it for the terminal, the docs pass it through, and man generation demotes the headings for md2man. gendocs gains golden coverage, and one example which documented the wrong key order is corrected.
This x PR should be merged first as this PR depends on this one: unikraft-cloud/x#462
The original approach was to infer the headings/code tabs from the plaintext content as in (#496) however this was too fragile so changing the help text to markdown adds structure and is more reliable