docs: Add documentation review guidance#3495
Conversation
|
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. |
Summary by CodeRabbit
WalkthroughAGENTS.md updates repository formatting guidance, expands the Documentation review checklist with code-evidence verification requirements, and replaces a Further Reading reference. ChangesDocumentation guidance
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
polarweasel
left a comment
polarweasel
left a comment
There was a problem hiding this comment.
Added some changes and some questions...
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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 `@AGENTS.md`:
- Around line 274-275: Update the documentation guidance near the public-page
requirements so redirects in fern/docs.yml are required only when public paths
are moved or removed, not for ordinary content changes at an unchanged path.
Keep the docs/index.yml requirement for new or moved public pages unchanged.
- Around line 296-303: Update the command examples in the documentation workflow
section of AGENTS.md to avoid raw angle-bracket placeholders that shells
interpret as redirection. Replace them with realistic concrete values or show
safely quoted variable definitions before using them, while preserving the
existing rumdl and Fern command behavior.
- Around line 226-227: Update the contract verification guidance in AGENTS.md to
require real --help comparison only for changed CLI examples. For APIs,
configuration, environment variables, and states, require appropriate validation
through schemas, handlers, or exercised outputs instead, while preserving
coverage of all changed interface types.
🪄 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: cb95787f-da8f-4dc2-99cf-176b86aa4fcb
📒 Files selected for processing (1)
AGENTS.md
| - Exercise each changed example at the PR revision on an authorized local or | ||
| test target and compare it with real `--help` output. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Limit --help verification to CLI examples.
The surrounding contract list also covers APIs, config, environment variables, and states, for which --help output is not applicable. Require --help comparison for CLI examples, and use schemas, handlers, or exercised output for other interfaces.
As per coding guidelines, interface-contract checks must cover non-CLI inputs as well as commands.
🤖 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 `@AGENTS.md` around lines 226 - 227, Update the contract verification guidance
in AGENTS.md to require real --help comparison only for changed CLI examples.
For APIs, configuration, environment variables, and states, require appropriate
validation through schemas, handlers, or exercised outputs instead, while
preserving coverage of all changed interface types.
Source: Coding guidelines
| - New or moved public pages must be present in `docs/index.yml`, and changed | ||
| public paths need redirects in `fern/docs.yml`. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Require redirects only for moved or removed public paths.
“Changed public paths need redirects” is overbroad: content changes at an existing path do not require redirects. Fern’s missing-redirects check concerns pages removed or moved without preserving their previous URLs. (buildwithfern.com)
🤖 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 `@AGENTS.md` around lines 274 - 275, Update the documentation guidance near the
public-page requirements so redirects in fern/docs.yml are required only when
public paths are moved or removed, not for ordinary content changes at an
unchanged path. Keep the docs/index.yml requirement for new or moved public
pages unchanged.
| - Run `rumdl check --config docs/.rumdl.toml <changed-markdown-files>` and fail | ||
| on every finding. | ||
| - For Fern-published pages, inspect the CI-created PR preview. A local | ||
| `fern docs dev` preview works without a Fern token, but does not apply the | ||
| global `nvidia` theme without one. | ||
| - If a hosted preview must be created manually, run | ||
| `fern generate --docs --preview --id <stable-id>`, then delete it after | ||
| review with `fern docs preview delete --id <stable-id>`. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make shell placeholders safe to copy.
Values such as <changed-markdown-files> and <stable-id> are interpreted by the shell as redirection syntax when copied literally. Use concrete examples or define quoted variables before invoking these commands.
As per path instructions, Markdown commands and examples must be realistic and safe.
🤖 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 `@AGENTS.md` around lines 296 - 303, Update the command examples in the
documentation workflow section of AGENTS.md to avoid raw angle-bracket
placeholders that shells interpret as redirection. Replace them with realistic
concrete values or show safely quoted variable definitions before using them,
while preserving the existing rumdl and Fern command behavior.
Source: Path instructions
🔍 Container Scan Summary
Per-CVE detail lives in the per-service |
2 participants
No description provided.