docs: improve landing pages and about pages#3371
Conversation
|
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 (2)
✅ Files skipped from review due to trivial changes (2)
📝 WalkthroughWalkthroughThis pull request restructures the NemoClaw documentation to emphasize a new three-part architecture (host CLI, TypeScript sandbox plugin, versioned YAML blueprint), reorganizes the ecosystem and overview descriptions, and improves navigation across the documentation site through updated landing pages and quickstart guides. ChangesDocumentation Restructuring for Architecture & Navigation Update
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Comment |
E2E Advisor RecommendationRequired E2E: None Dispatch hint: Full advisor summaryPi Semantic E2E AdvisorBase: Required E2E
Optional E2E
New E2E recommendations
Dispatch hint
|
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (4)
docs/about/ecosystem.md (2)
31-32: ⚡ Quick winSwitch passive wording to active voice in the opening sentence.
Line 31 uses passive construction (“are put together”). Rephrase in active voice.
As per coding guidelines, "Active voice required. Flag passive constructions."
🤖 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/about/ecosystem.md` around lines 31 - 32, Change the passive sentence "There are three pieces that are put together in a NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct scope." to active voice by making the subject perform the action (for example: "Three components make up a NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct scope.") — update the opening sentence in docs/about/ecosystem.md accordingly to satisfy the "Active voice required" guideline.
31-31: ⚡ Quick winAvoid colons in prose clauses where no list follows.
These colons act as general punctuation rather than introducing lists. Use a period or comma structure instead.
As per coding guidelines, "Colons should only introduce a list. Flag colons used as general punctuation between clauses."
Also applies to: 64-64, 66-66
🤖 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/about/ecosystem.md` at line 31, The sentence "There are three pieces that are put together in a NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct scope." uses a colon as general punctuation; update that sentence (and the similar lines at 64 and 66) to remove the colon and use a period or comma structure instead (e.g., "There are three pieces that are put together in a NemoClaw deployment. OpenClaw, OpenShell, and NemoClaw each have a distinct scope." or "There are three pieces that are put together in a NemoClaw deployment — OpenClaw, OpenShell, and NemoClaw — each with a distinct scope.") so colons only introduce actual lists.docs/about/overview.md (2)
23-23: ⚡ Quick winAlign H1 with frontmatter page title.
The H1 does not match
title.page("NemoClaw Overview: What It Is"), which breaks the page-structure rule for docs pages.As per coding guidelines, "H1 heading matches the
title.pagefrontmatter value."🤖 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/about/overview.md` at line 23, The H1 heading currently reads "Overview of NVIDIA NemoClaw" but must match the frontmatter key title.page ("NemoClaw Overview: What It Is"); update the top-level H1 in this document to exactly "NemoClaw Overview: What It Is" so the page title and H1 are identical and comply with the page-structure rule.
48-48: ⚡ Quick winSplit this into one sentence per source line.
This line currently contains multiple sentences; docs require one sentence per line for review-friendly diffs.
As per coding guidelines, "One sentence per line in source (makes diffs readable). Flag paragraphs where multiple sentences appear on the same line."
🤖 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/about/overview.md` at line 48, The table row containing "Messaging channels | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the sandboxed agent. NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision." should be split so each sentence occupies its own source line; update the cell so one line reads "Messaging channels | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the sandboxed agent." and the next line reads "NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision." thereby ensuring one sentence per line while preserving the table structure and wording (references: the "Messaging channels" table row and the NemoClaw sentence).
🤖 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/about/how-it-works.md`:
- Line 3: The page title string page: "NemoClaw Architecture Overview: Plugin,
Blueprint, and Sandbox Lifecycle" contains a colon which violates the docs title
rule; update that string to a no-colon variant (e.g., replace the colon with
"and" or split wording) so it reads something like page: "NemoClaw Architecture
Overview and Plugin, Blueprint, and Sandbox Lifecycle" (or another clear
no-colon phrasing) to satisfy the guideline; ensure you only change the title
string value.
In `@docs/about/overview.md`:
- Line 31: The docs line currently links to the third-party repo
"https://github.com/NVIDIA/OpenShell" which violates the markdown rule; remove
the hyperlink and either leave "NVIDIA OpenShell" as plain text or replace it
with a non-link reference (e.g., "NVIDIA OpenShell (project)") in the sentence
that mentions the sandbox runtime and the `nemoclaw` CLI so the prose no longer
contains an external GitHub link.
- Line 28: Update the sentence "This enables self-evolving claws to run more
safely in clouds, on prem, RTX PCs and DGX Spark." to use hyphenated "on-prem"
instead of "on prem" so it reads "This enables self-evolving claws to run more
safely in clouds, on-prem, RTX PCs and DGX Spark."; ensure only the
spacing/hyphenation is changed and no other wording is altered.
In `@docs/get-started/quickstart-hermes.md`:
- Around line 30-33: Replace the unsupported MyST admonition type "admonition"
with a supported callout such as "warning" (or "note"/"tip") in the Hermes agent
block so it conforms to the docs callout rule; specifically update the opening
tag :::{admonition} to :::{warning} (and keep the same inner text and closing
:::) so the Hermes experimental feature note uses a valid MyST admonition.
In `@docs/index.md`:
- Line 143: The sentence "To find detailed instruction on the installation
process, refer to the [Quickstart](get-started/quickstart.md) guide." uses
singular "instruction" incorrectly; update that phrase to "detailed
instructions" so the sentence reads "To find detailed instructions on the
installation process, refer to the [Quickstart](get-started/quickstart.md)
guide." and keep the rest of the sentence and link unchanged.
---
Nitpick comments:
In `@docs/about/ecosystem.md`:
- Around line 31-32: Change the passive sentence "There are three pieces that
are put together in a NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw,
each with a distinct scope." to active voice by making the subject perform the
action (for example: "Three components make up a NemoClaw deployment: OpenClaw,
OpenShell, and NemoClaw, each with a distinct scope.") — update the opening
sentence in docs/about/ecosystem.md accordingly to satisfy the "Active voice
required" guideline.
- Line 31: The sentence "There are three pieces that are put together in a
NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct
scope." uses a colon as general punctuation; update that sentence (and the
similar lines at 64 and 66) to remove the colon and use a period or comma
structure instead (e.g., "There are three pieces that are put together in a
NemoClaw deployment. OpenClaw, OpenShell, and NemoClaw each have a distinct
scope." or "There are three pieces that are put together in a NemoClaw
deployment — OpenClaw, OpenShell, and NemoClaw — each with a distinct scope.")
so colons only introduce actual lists.
In `@docs/about/overview.md`:
- Line 23: The H1 heading currently reads "Overview of NVIDIA NemoClaw" but must
match the frontmatter key title.page ("NemoClaw Overview: What It Is"); update
the top-level H1 in this document to exactly "NemoClaw Overview: What It Is" so
the page title and H1 are identical and comply with the page-structure rule.
- Line 48: The table row containing "Messaging channels | OpenShell-managed
processes connect Telegram, Discord, Slack, and similar platforms to the
sandboxed agent. NemoClaw configures channels during onboarding; OpenShell
supplies the native constructs, credential flow, and runtime supervision."
should be split so each sentence occupies its own source line; update the cell
so one line reads "Messaging channels | OpenShell-managed processes connect
Telegram, Discord, Slack, and similar platforms to the sandboxed agent." and the
next line reads "NemoClaw configures channels during onboarding; OpenShell
supplies the native constructs, credential flow, and runtime supervision."
thereby ensuring one sentence per line while preserving the table structure and
wording (references: the "Messaging channels" table row and the NemoClaw
sentence).
🪄 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: 3aad401e-d879-4226-a037-5f5af24ce16c
⛔ Files ignored due to path filters (1)
docs/about/images/nemoclaw-highlevel-component-diagram.pngis excluded by!**/*.png
📒 Files selected for processing (9)
README.mddocs/about/ecosystem.mddocs/about/how-it-works.mddocs/about/overview.mddocs/get-started/prerequisites.mddocs/get-started/quickstart-hermes.mddocs/get-started/quickstart.mddocs/index.mddocs/reference/architecture.md
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
ericksoa
left a comment
There was a problem hiding this comment.
Reviewed the docs changes and linked diagram against #2602, checked the PR head against current main, and verified local docs validation with npm run docs:strict plus the docs-to-skills dry run. No regression blockers found.
Summary
Refresh the Get Started and About documentation so new users are directed to the right overview and quickstart pages from the entry pages.
Adds the high-level component diagram to Architecture Overview and aligns the entry pages around the intended reading path from Overview to Ecosystem, How It Works, and then Quickstart.
Preview: https://nvidia.github.io/NemoClaw/pr-preview/pr-3371/
Related Issue
Closes #2602
Changes
docs/about/how-it-works.md.Type of Change
Verification
npx prek run --all-filespassesnpm testpassesmake docsbuilds without warnings (doc changes only)Summary by CodeRabbit