docs: standardize copyable command examples#4759
Conversation
… error in sync-agent-variant-docs.ts:101, which throws "commands.mdx must start with YAML frontmatter when run on this environment." This is because the yaml formatting check is strict to only look for UNIX-style LF endings, and is not resilient for Windows-style CRLF endings. This makes the regex more robust, and lets the check pass on Windows environments.
…le commands from their example output sections to make it easier for users to know how / when to follow along. Commands are now clearly labeled as console/bash/powershell, and output is labeled as json/text
…ting copy-pasteable commands from blocks that contain example output. Resolves NVIDIA#4754
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: 📒 Files selected for processing (4)
✅ Files skipped from review due to trivial changes (4)
📝 WalkthroughWalkthroughStandardizes documentation code-block formatting across the repository, updates CONTRIBUTING.md with explicit code-block rules, applies those rules across multiple MDX docs (removing prompt prefixes and adding separate "Expected output" fences), and makes frontmatter parsing accept optional BOM and CRLF. ChangesDocumentation formatting standardization
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 11
🧹 Nitpick comments (1)
docs/reference/troubleshooting.mdx (1)
1500-1500: ⚡ Quick winUse consistent output label formatting.
This segment uses "Example output:" while other similar segments in this file (lines 1017, 1056, 1152, 1162) use "Expected output:". Choose one format and apply it consistently throughout the file.
📝 Suggested change for consistency
-Example output: +Expected output:🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/troubleshooting.mdx` at line 1500, Replace the inconsistent label "Example output:" with the project's standard "Expected output:" in the troubleshooting segment (the literal string "Example output:" shown in the diff); update that occurrence so it matches other segments that use "Expected output:" and briefly scan nearby similar headings ("Expected output:") to ensure uniform formatting across the document.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/reference/troubleshooting.mdx`:
- Around line 1013-1015: Replace the code block language tag for the single
copyable CLI command `curl -s http://10.0.0.5:50001/health` in the
`troubleshooting.mdx` content: change the opening fence from ```console to
```bash so the block is treated as a copyable bash snippet (no prompt/output),
ensuring the command uses the language-specific tag per the contributing
guidelines.
- Around line 1496-1498: Replace the markdown code fence language tag from
"console" to "bash" for the health-check block containing "curl -sf
http://127.0.0.1:8642/health" so the command is copyable; ensure the fenced
block contains only the raw curl command (no prompts or output) and uses ```bash
... ``` instead of ```console ... ```.
- Around line 1535-1538: Replace the fenced code block language tag "console"
with "bash" for the copyable CLI commands; specifically update the block
containing the two lines "command -v nemoclaw" and "command -v nemohermes" so it
reads a bash code block (no prompt markers) to follow the guideline that
copyable commands use language-specific tags like bash/sh.
- Around line 1582-1583: Replace the fenced code block language tag from
`console` to `bash` for the CLI example that shows the command "nemohermes
credentials list" so the snippet is copyable; locate the fenced block containing
that command (the existing block labeled `console`) and change its opening fence
to use `bash` (ensuring no prompt markers like `$` are present).
- Around line 1052-1054: Change the code fence language for the single-line curl
example containing "curl -s http://10.0.0.5:50001/health" from console to bash
so it becomes a copyable CLI block; ensure the fenced block uses ```bash and
contains only the bare command (no prompt markers) to comply with the copyable
CLI guidelines.
- Around line 1148-1150: Replace the fenced code block language tag "console"
with "bash" for the single copyable command shown (the getent hosts
host.docker.internal snippet) so it becomes a copyable bash block; locate the
fenced block containing "getent hosts host.docker.internal" in the
troubleshooting.mdx content and update the opening triple-backtick language
identifier accordingly, ensuring no prompt markers are added.
- Around line 1556-1565: Replace the code block language tag "console" with
"bash" for the two CLI examples so they are copyable shell commands (keep the
existing lines: export NEMOCLAW_HERMES_AUTH_METHOD=oauth, nemohermes onboard,
export NEMOCLAW_HERMES_AUTH_METHOD=api-key, export NOUS_API_KEY=..., nemohermes
onboard --non-interactive), ensuring no prompt markers are added; locate the
block currently wrapped with ```console``` and change it to ```bash``` in
docs/reference/troubleshooting.mdx.
- Around line 1599-1604: Replace the code block language tag from "console" to
"bash" for the CLI snippet that sets TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN,
SLACK_BOT_TOKEN and runs "nemohermes onboard --resume --non-interactive" so the
export commands are copyable; ensure the block starts with ```bash and contains
only the raw export lines and the nemohermes command (no prompt markers).
- Around line 1543-1545: Update the code block language tag from "console" to
"bash" for the installer snippet and ensure the block contains only the copyable
commands (no prompt markers); locate the snippet with the export and curl
pipeline (the block that currently shows "export NEMOCLAW_AGENT=hermes" and
"curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash") and replace the opening
fence language so it reads as a bash code block.
- Around line 1159-1161: Change the copyable CLI block that currently uses the
`console` language tag to `bash` for the curl command; locate the block
containing the literal `no_proxy=host.docker.internal curl -v
http://host.docker.internal:11434/api/tags` and update its fence language from
`console` to `bash` so it becomes a copyable bash snippet (no prompts or output
lines should be included).
- Around line 1523-1526: Change the code block language from "console" to "bash"
and remove prompt markers so the commands are copyable: replace the ```console
fence with ```bash and strip the leading "$" (and any extra whitespace following
it) from the two lines " $$nemoclaw <name> destroy" and " NEMOCLAW_AGENT=hermes
nemohermes onboard" so the block contains plain bash commands only.
---
Nitpick comments:
In `@docs/reference/troubleshooting.mdx`:
- Line 1500: Replace the inconsistent label "Example output:" with the project's
standard "Expected output:" in the troubleshooting segment (the literal string
"Example output:" shown in the diff); update that occurrence so it matches other
segments that use "Expected output:" and briefly scan nearby similar headings
("Expected output:") to ensure uniform formatting across the document.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 6d6cbf32-e670-4afa-940e-b98d377a567f
📒 Files selected for processing (8)
docs/CONTRIBUTING.mddocs/inference/switch-inference-providers.mdxdocs/manage-sandboxes/backup-restore.mdxdocs/monitoring/monitor-sandbox-activity.mdxdocs/reference/commands-nemohermes.mdxdocs/reference/commands.mdxdocs/reference/troubleshooting.mdxscripts/sync-agent-variant-docs.ts
|
✨ Thanks for submitting this detailed PR about updating documentation standards to improve console block formatting and adopting a clear split between copyable commands and their expected output. This proposes a way to address the documentation gap and improve the overall documentation quality. Related open PRs: Related open issues: |
|
@HanClinto mind addressing the feedback comments and updating the PR title to make commit-lint pass? |
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/inference/switch-inference-providers.mdx (1)
235-250:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUse
bashinstead ofconsolefor copyable commands.The copyable command blocks use
consoletags, but according to the coding guidelines, single copyable commands should use language-specific tags likebash. Reserveconsolefor terminal transcripts that include prompts, output, or interactive sessions.📝 Proposed fix
-```console +```bash $$nemoclaw inference getExpected output:
Provider: nvidia-prod Model: nvidia/nemotron-3-super-120b-a12bPass
--jsonfor machine-readable output.-
console +bash
$$nemoclaw inference get --jsonAs per coding guidelines: "Copyable CLI code blocks must use language-specific tags such as
bash,sh, orpowershell, and must not include prompt markers such as$. Reserveconsoleblocks for terminal transcripts that include prompts, output, or interactive sessions."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/inference/switch-inference-providers.mdx` around lines 235 - 250, Replace the two ```console blocks with ```bash and make the commands copyable by removing any prompt markers (remove the leading "$" or "$$") so the example commands use plain text "nemoclaw inference get" and "nemoclaw inference get --json"; update the surrounding fenced blocks (the Expected output block stays as-is) and ensure you use bash language tags for both command blocks.Source: Coding guidelines
docs/CONTRIBUTING.md (1)
254-260:⚠️ Potential issue | 🟠 Major | ⚡ Quick winInconsistency with coding guidelines on
consoleusage.Line 256 states: "Use
consoleonly when a command is shell-agnostic and intended to be copied as-is."However, the coding guidelines explicitly state: "Copyable CLI code blocks must use language-specific tags such as
bash,sh, orpowershell, and must not include prompt markers such as$. Reserveconsoleblocks for terminal transcripts that include prompts, output, or interactive sessions."This means
consoleshould be reserved for transcripts (with prompts/output), NOT for copyable commands—even shell-agnostic ones. Copyable shell-agnostic commands should usebashas the language tag.📝 Suggested fix
- Use `powershell` for Windows PowerShell commands. Use `bash` or `sh` for Linux, macOS, and WSL shell commands. - Use `console` only when a command is shell-agnostic and intended to be copied as-is. Do not use prompt markers such as `$` in copyable command blocks. Keep command and output in separate fenced code blocks. For output blocks, use `json` when the output is valid JSON, otherwise use `text`. - For rare transcript-style examples that intentionally mix command and output, label the section as transcript-only so readers do not treat it as copy/paste input. + Reserve `console` blocks for transcript-style examples that intentionally mix command and output (including prompts); label these sections as transcript-only so readers do not treat them as copy/paste input.As per coding guidelines: "Copyable CLI code blocks must use language-specific tags such as
bash,sh, orpowershell, and must not include prompt markers such as$. Reserveconsoleblocks for terminal transcripts that include prompts, output, or interactive sessions."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/CONTRIBUTING.md` around lines 254 - 260, Update the sentence "Use `console` only when a command is shell-agnostic and intended to be copied as-is." to reflect the coding guideline: reserve `console` for terminal transcripts that include prompts/output or interactive sessions, and require copyable CLI blocks (including shell-agnostic examples) to use language-specific tags like `bash`, `sh`, or `powershell` with no prompt markers; ensure the doc explicitly states to prefer `bash` for generic copyable shell commands when a single tag is needed and to use `json` for JSON output blocks and `text` otherwise.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@docs/CONTRIBUTING.md`:
- Around line 254-260: Update the sentence "Use `console` only when a command is
shell-agnostic and intended to be copied as-is." to reflect the coding
guideline: reserve `console` for terminal transcripts that include
prompts/output or interactive sessions, and require copyable CLI blocks
(including shell-agnostic examples) to use language-specific tags like `bash`,
`sh`, or `powershell` with no prompt markers; ensure the doc explicitly states
to prefer `bash` for generic copyable shell commands when a single tag is needed
and to use `json` for JSON output blocks and `text` otherwise.
In `@docs/inference/switch-inference-providers.mdx`:
- Around line 235-250: Replace the two ```console blocks with ```bash and make
the commands copyable by removing any prompt markers (remove the leading "$" or
"$$") so the example commands use plain text "nemoclaw inference get" and
"nemoclaw inference get --json"; update the surrounding fenced blocks (the
Expected output block stays as-is) and ensure you use bash language tags for
both command blocks.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: dc152fb4-e444-4654-ae62-c85e2ca9bcb1
📒 Files selected for processing (6)
docs/CONTRIBUTING.mddocs/inference/switch-inference-providers.mdxdocs/reference/commands-nemohermes.mdxdocs/reference/commands.mdxdocs/reference/troubleshooting.mdxscripts/sync-agent-variant-docs.ts
✅ Files skipped from review due to trivial changes (1)
- docs/reference/commands.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/reference/commands-nemohermes.mdx
Thanks for the ping -- please pardon my delay in circling back to this. Yes, I'll address the feedback and update the PR title. One thing that was curious to me is that CodeRabbit seems to have been leaving feedback by using the old standards of CONTRIBUTING.md -- but I'm proposing an update of the standards as part of this PR. I guess I should ask a human like you -- are the changed standards I'm proposing for the usage of "console" vs. "bash" and whatnot reasonable? Even beyond that, there are some other things I need to change to make it consistent, so I'll plan to do that later tonight or tomorrow -- I should have some time this weekend. |
HanClinto
changed the title
Clarify that copyable command blocks should use language-specific fences and reserve console blocks for transcript-style examples. Use Expected output labels consistently and update the changed docs to match the new command/output formatting guidance.
## Summary - Add the v0.0.61 release notes from the GitHub dev announcement. - Document managed vLLM recovery after host reboot and Slack denied-mention feedback. - Refresh generated `nemoclaw-user-*` skills from the source docs. ## Source summary - #4983 -> `docs/about/release-notes.mdx`: Added the v0.0.61 release summary from the dev announcement and linked behavior groups to deeper docs. - #4904 -> `docs/inference/use-local-inference.mdx`: Documented that managed vLLM restarts the `nemoclaw-vllm` container after host reboot during recovery. - #4933 -> `docs/manage-sandboxes/messaging-channels.mdx`: Documented Slack sender feedback for denied channel `@mention` events. - #4879, #4915, #4935, #4759, #4164, #4888, #4897, #4944, #4959 -> `.agents/skills/`: Refreshed generated user skills from the current source docs for release prep. ## Verification - `python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx` - `npm run docs` (passed outside the tool sandbox after `tsx` IPC pipe creation was blocked in the sandbox) - `npm run build:cli` (refreshed local `dist/` for the pre-push TypeScript hook) - Commit and pre-push hooks passed, including docs-to-skills verification, markdownlint, gitleaks, skills YAML tests, and CLI TypeScript. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated sandbox security documentation with file descriptor limits. * Changed default inference model for DGX Station profile. * Enhanced agent policy and backup/restore documentation. * Improved command reference examples with clearer formatting. * Clarified Slack messaging denial notice behavior. * Added automatic vLLM container recovery during host reboot. * Updated release notes for v0.0.61. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
3 participants
Summary
Updates the documentation standards by removing
$prefixes from copy-pasteable console blocks, and also adopting a clear split between copyable commands and their example expected transcript output. Part of this PR is a standards change, and part of it is just updating the last few files that were missed by #3909.Related Issue
#4754
Changes
docs/CONTRIBUTING.mdto request a general split between copyable commands and their expected output.console,powershell, orbashlabel, while the expected output receives ajsonortextlabel (according to its contents).$prefix removal from "Copy" Shortcut for Quick Install Commands Include $ Prefix (Windows) #3847Type of Change
Verification
npx prek run --all-filespasses (skipped for now, as this doesn't seem to like Windows as a host)npm testpassesnpm run docsbuilds without warnings (doc changes only)Signed-off-by: Clint Herron hanclinto@gmail.com
Summary by CodeRabbit
json/textoutput fences, forbid prompt markers in copyable commands, restrict mixed command+output to labeled transcript-only sections, and updated numerous example snippets and command-reference pages to this format.