docs: hide generated variant pages by miyoungc · Pull Request #4724 · NVIDIA/NemoClaw

miyoungc · 2026-06-03T21:21:01Z

Summary

Moves generated OpenClaw/Hermes lifecycle docs out of the source directory and into the ignored docs build tree. This keeps contributor-facing source folders free of generated page copies while preserving Fern's native rendering for variant pages.

Changes

Generate variant pages under docs/_build/ instead of beside the original docs file.
Rewrite relative links when generating variant pages so links resolve from the _build output location.
Point Fern navigation at the hidden generated pages and document the variant-generation flow.
Extend the focused variant docs test to cover rewritten relative links.

Type of Change

Code change (feature, bug fix, or refactor)
Code change with doc updates
Doc only (prose changes, no code sample modifications)
Doc only (includes code sample changes)

Verification

git commit --no-verify and git push --no-verify were used at the user's request.

npx prek run --all-files passes
npm test passes
Tests added or updated for new or changed behavior
No secrets, API keys, or credentials committed
Docs updated for user-facing behavior changes
npm run docs builds without warnings (doc changes only)
Doc pages follow the style guide (doc changes only)
New doc pages include SPDX header and frontmatter (new pages only)

Verified locally:

npm test -- test/agent-variant-docs.test.ts
npm run docs (passes with existing Fern warning)

Signed-off-by: Miyoung Choi miyoungc@nvidia.com

Summary by CodeRabbit

New Features
- Introduced agent variant documentation generation with automatic link rewriting to ensure correct navigation in generated pages.
Documentation
- Added "Agent Variant Generation" section to contributing guidelines explaining how to create shared documentation that generates multiple variant versions.
Tests
- Updated test cases to validate variant-specific placeholder rendering and link path rewriting functionality.

coderabbitai · 2026-06-03T21:21:14Z

📝 Walkthrough

Walkthrough

This PR implements a build-time documentation generation system that creates variant-specific pages (OpenClaw and Hermes) from shared Fern source files using placeholder substitution. Generated MDX output is written to docs/_build/agent-variants/ with relative link targets automatically rewritten to resolve correctly from the new location.

Changes

Agent Variant Documentation Generation

Layer / File(s)	Summary
Rendering options and type definitions `scripts/sync-agent-variant-docs.ts`	Introduces `RenderAgentVariantOptions` interface with optional `sourcePath` and `outputPath` fields to parameterize variant rendering and enable path-aware link rewriting.
Link rewriting helpers `scripts/sync-agent-variant-docs.ts`	Adds utility functions to parse and rewrite Markdown link targets: preserves anchors/absolute URLs/schemes, and computes filesystem-relative paths for relative targets based on source and output directories, normalizing separators and preserving query/hash suffixes.
Rendering function and variant generation integration `scripts/sync-agent-variant-docs.ts`	Extends `renderAgentVariantPage` to accept options and apply link rewriting when both source and output paths are provided; updates `renderGeneratedAgentVariantPages` to output variant files under `generatedDocsRoot` and pass source/output paths to the renderer for per-variant link correction.
Build configuration and documentation `.gitignore`, `docs/CONTRIBUTING.md`, `docs/index.yml`	Removes `.gitignore` rule blocking `docs/*/.generated.mdx` to allow generated files into the repository; adds "Agent Variant Generation" guide explaining placeholder authoring and build commands; updates sidebar navigation to reference newly generated pages under `_build/agent-variants/`.
Test suite updates `test/agent-variant-docs.test.ts`	Updates OpenClaw and Hermes variant tests to validate placeholder rendering; adds new test case that verifies relative Markdown links are correctly rewritten when rendering with source/output path metadata.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

documentation

🐰 From shared source, variants spring free,
Links rewritten to their destined tree,
Build-time magic, paths set right,
OpenClaw and Hermes both take flight!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the primary change: moving generated variant pages to a hidden build directory (_build) rather than keeping them in the source tree.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/improve-variant-build

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions · 2026-06-03T21:21:46Z

🌿 Preview your docs: https://nvidia-preview-pr-4724.docs.buildwithfern.com/nemoclaw

github-actions · 2026-06-03T21:22:22Z

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

None. No E2E is required. This PR is limited to documentation navigation/content, docs generation tooling, ignore rules for generated docs, and a corresponding unit test. It cannot affect NemoClaw runtime/user flows such as install/onboarding, sandbox lifecycle, credentials, security boundaries, network policy enforcement, inference routing, or deployment behavior. Standard docs validation/unit checks such as npm run docs and the agent-variant docs test are the appropriate coverage.

Optional E2E

None.

New E2E recommendations

None.

github-actions · 2026-06-03T21:22:23Z

E2E Scenario Advisor Recommendation

Required scenario E2E: None
Optional scenario E2E: None

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

None. No scenario E2E is recommended because the PR changes docs, a docs generation script, a unit test for that script, and .gitignore only. It does not touch test/e2e-scenario/, the scenario workflows, scenario metadata, expected-state contracts, suite definitions, runtime code, onboarding/install helpers, or suite scripts used by scenario E2E.

Optional scenario E2E

None.

Relevant changed files

None.

github-actions · 2026-06-03T21:25:56Z

PR Review Advisor

Findings: 0 needs attention, 0 worth checking, 0 nice ideas
Top item: No actionable code findings

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

docs: hide generated variant pages

95b5630

miyoungc added the area: docs Documentation, examples, guides, or docs build label Jun 3, 2026

miyoungc self-assigned this Jun 3, 2026

cv approved these changes Jun 3, 2026

View reviewed changes

miyoungc enabled auto-merge (squash) June 3, 2026 21:25

miyoungc merged commit d798d5e into main Jun 3, 2026
40 checks passed

miyoungc deleted the docs/improve-variant-build branch June 3, 2026 21:28

This was referenced Jun 3, 2026

docs: expand generated agent variants #4728

Merged

docs: fix generated variant route links #4737

Merged

wscurran added the chore Build, CI, dependency, or tooling maintenance label Jun 8, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: hide generated variant pages#4724

docs: hide generated variant pages#4724
miyoungc merged 1 commit into
mainfrom
docs/improve-variant-build

miyoungc commented Jun 3, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 3, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Suggested labels

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Jun 3, 2026

Uh oh!

github-actions Bot commented Jun 3, 2026

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Uh oh!

github-actions Bot commented Jun 3, 2026

E2E Scenario Advisor

Required scenario E2E

Optional scenario E2E

Relevant changed files

Uh oh!

github-actions Bot commented Jun 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

miyoungc commented Jun 3, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Type of Change

Verification

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Suggested labels

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Jun 3, 2026

Uh oh!

github-actions Bot commented Jun 3, 2026

E2E Advisor Recommendation

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Uh oh!

github-actions Bot commented Jun 3, 2026

E2E Scenario Advisor Recommendation

E2E Scenario Advisor

Required scenario E2E

Optional scenario E2E

Relevant changed files

Uh oh!

github-actions Bot commented Jun 3, 2026

PR Review Advisor

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

miyoungc commented Jun 3, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 3, 2026 •

edited

Loading