docs: fix accuracy across docs and clean up build pipeline#323
Conversation
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughConsolidates documentation and docs-site tooling, standardizes Homebrew install commands, updates MCP docs to reflect 17 tools (adds walk_headers and walk_refs plus new inputs), removes five docs from .gitignore, adjusts Makefile/markdown-lint targets and docs-clean behavior, and deletes 30+ planning/design files under docs/plans. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #323 +/- ##
=======================================
Coverage 84.52% 84.52%
=======================================
Files 184 184
Lines 26716 26716
=======================================
Hits 22583 22583
Misses 2812 2812
Partials 1321 1321 🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Fix all issues with AI agents
In @.claude/docs/docs-website.md:
- Line 65: Add a single trailing newline at the end of the file by inserting one
blank line after the final sentence "The prepare-docs script explicitly skips
`index.md`." so the file ends with exactly one newline character (ensure no
extra blank lines beyond that).
- Around line 16-22: The docs-clean description is inaccurate: either update the
docs-website.md entry for the Make target docs-clean to list the actual paths it
removes (site/, .tmp/, log files, docs/packages/) or modify the Make target
docs-clean itself to also remove docs/examples/ (which is created by
docs-prepare per CLAUDE.md). Edit the docs-website.md line for "make docs-clean"
to match the current behavior or adjust the Makefile's docs-clean recipe to
include deletion of docs/examples/, and keep the
docs-serve/docs-start/docs-build notes unchanged.
In `@CLAUDE.md`:
- Line 48: Prefix the existing bullet text "**`docs/` is mixed source +
generated**: Source files (`index.md`, `mcp-server.md`, `cli-reference.md`,
etc.) are edited directly in `docs/`. Generated files (`docs/packages/`,
`docs/examples/`) come from `{package}/deep_dive.md` and `examples/*/README.md`
— see `.claude/docs/docs-website.md`" with one of the approved emojis (✅❌🔴🟡⚠️)
to match the markdown emoji guideline; edit CLAUDE.md and prepend your chosen
emoji (e.g., "✅ ") directly before the bold bullet text so the bullet reads "✅
**`docs/` is mixed source + generated**: …".
In `@docs/claude-code-plugin.md`:
- Around line 92-99: The "17 MCP Tools" heading needs an approved emoji prefix
for scannability; update the Markdown heading "17 MCP Tools" to start with one
of the allowed emojis (for example "✅ 17 MCP Tools") so the heading reads with
the emoji followed by the existing title, leaving the rest of the section (the
Core and Walk tool lists like `validate`, `parse`, `walk_operations`, etc.)
unchanged.
In `@docs/index.md`:
- Line 42: The change was made in the generated file docs/index.md which gets
overwritten; instead edit the source README.md at the repo root and re-run the
docs generation script (scripts/prepare-docs.sh) to propagate the change, i.e.,
move the updated sentence from docs/index.md into README.md (keeping the same
wording about Model Context Protocol and MCP-compatible agents) and run
scripts/prepare-docs.sh to regenerate docs/index.md.
In `@docs/mcp-server.md`:
- Around line 5-15: The "Prerequisites" and "Tools (17)" markdown headings need
an emoji prefix for scannability; update the heading lines containing the exact
text "Prerequisites" and "Tools (17)" to start with one of the allowed emojis (✅
❌ 🔴 🟡 ⚠️) per guidelines (e.g., "✅ Prerequisites" and "✅ Tools (17)"), and
apply the same change to the other headings referenced around lines 53-56
(replace their heading starts with an allowed emoji while preserving heading
level and content).
erraggy
force-pushed
the
docs/fix-docs-accuracy-and-pipeline
branch
2 times, most recently
from
c899c0b to
55689da
Compare
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (16)
.claude/agents/maintainer.md (1)
14-21: 🧹 Nitpick | 🔵 TrivialAdd emoji markers to new list items for scannability.
Multiple new bullet/numbered lists were added without emojis; the docs guideline requires emojis in Markdown lists to improve scanning. Please add ✅/
⚠️ /🔴/🟡 (as appropriate) to the newly added list items and checklists in these sections.As per coding guidelines: "Use emojis (✅❌🔴🟡
⚠️ ) in documentation for scannability."Also applies to: 24-62, 65-98, 101-132, 146-226, 229-235
CONTRIBUTORS.md (1)
54-61: 🧹 Nitpick | 🔵 TrivialAdd emojis to updated list items for scannability.
The changed list blocks still use plain bullets/numbered items. Please add emojis (✅/
⚠️ /🟡/🔴) to the newly touched list items to match the Markdown scannability guideline.As per coding guidelines: "Use emojis (✅❌🔴🟡
⚠️ ) in documentation for scannability."Also applies to: 128-139, 188-195, 225-233, 273-277, 319-327, 375-388, 394-406, 409-425, 454-477, 480-491, 510-523, 592-597
.claude/skills/prepare-release/SKILL.md (1)
10-67: 🧹 Nitpick | 🔵 TrivialAdd emoji markers to the newly added lists/steps.
The new lists and step bullets are emoji-free. Please add ✅/
⚠️ /🟡/🔴 markers to improve scanability per the Markdown guideline.As per coding guidelines: "Use emojis (✅❌🔴🟡
⚠️ ) in documentation for scannability."Also applies to: 73-122, 129-156, 163-170, 175-223, 227-250, 253-267
.claude/agents/test-writer.md (1)
14-20: 🧹 Nitpick | 🔵 TrivialAdd emojis to the newly added bullet lists.
Please add ✅/
⚠️ /🟡/🔴 markers to the new bullets to match the Markdown scannability guideline.As per coding guidelines: "Use emojis (✅❌🔴🟡
⚠️ ) in documentation for scannability."Also applies to: 45-51, 154-158
RELEASES.md (1)
33-38: 🧹 Nitpick | 🔵 TrivialAdd emojis to updated list items for scannability.
The newly touched lists in these sections are still emoji-free. Please add ✅/
⚠️ /🟡/🔴 markers to align with the Markdown documentation guideline.As per coding guidelines: "Use emojis (✅❌🔴🟡
⚠️ ) in documentation for scannability."Also applies to: 83-88, 99-105, 113-118, 123-135, 160-168, 185-189, 239-244, 246-253, 258-262, 266-270, 343-346
WORKFLOW.md (1)
34-696:⚠️ Potential issue | 🟡 MinorAdd emojis to new/edited bullet lists for scannability.
Several updated checklist/bullet sections are plain text (e.g., pre-commit checklist, PR workflow steps, release steps, quick reference commands). Please prefix bullets with ✅❌🔴🟡
⚠️ to align with the doc style guideline.
As per coding guidelines, "Use emojis (✅❌🔴🟡⚠️ ) in documentation for scannability".AGENTS.md (1)
16-254:⚠️ Potential issue | 🟡 MinorAdd emoji prefixes to new bullets for scannability.
Multiple updated bullet lists (e.g., testing requirements, code style patterns, common pitfalls, agent files) lack the required ✅❌🔴🟡
⚠️ prefixes.
As per coding guidelines, "Use emojis (✅❌🔴🟡⚠️ ) in documentation for scannability"..claude/agents/developer.md (1)
14-374:⚠️ Potential issue | 🟡 MinorPrefix new bullets with emojis for scannability.
The newly added lists (activation triggers, phase steps, testing requirements, gopls guidance, etc.) are plain bullets. Please add ✅❌🔴🟡
⚠️ prefixes to align with doc standards.
As per coding guidelines, "Use emojis (✅❌🔴🟡⚠️ ) in documentation for scannability".docs/developer-guide.md (1)
34-2166:⚠️ Potential issue | 🟠 MajorMove these edits to the root source file and regenerate docs/.
This file is under docs/, which the guidelines treat as generated output. Please apply the changes in the corresponding source file at the repository root and then regenerate docs/. Also ensure emoji prefixes are added to the updated bullet lists in the source.
As per coding guidelines, "Always edit source files at repository root, not generated files in docs/ directory"..claude/docs/oas-concepts.md (1)
14-107:⚠️ Potential issue | 🟡 MinorAdd emoji prefixes to new bullet lists.
The new version-specific and pitfalls bullet lists are plain text. Please add ✅❌🔴🟡
⚠️ prefixes to comply with documentation style.
As per coding guidelines, "Use emojis (✅❌🔴🟡⚠️ ) in documentation for scannability".benchmarks.md (1)
51-565:⚠️ Potential issue | 🟡 MinorAdd emoji prefixes to the new bullet lists for scannability.
The expanded benchmark bullets (performance achievements, suite details, best practices, methodology) should use ✅❌🔴🟡
⚠️ prefixes to match the doc standard.
As per coding guidelines, "Use emojis (✅❌🔴🟡⚠️ ) in documentation for scannability"..claude/agents/architect.md (1)
14-237:⚠️ Potential issue | 🟡 MinorPrefix new bullets with emojis for scannability.
New activation/responsibility/process/format lists should use ✅❌🔴🟡
⚠️ prefixes to match documentation style.
As per coding guidelines, "Use emojis (✅❌🔴🟡⚠️ ) in documentation for scannability".converter/deep_dive.md (2)
31-598:⚠️ Potential issue | 🟡 MinorAdd emoji prefixes to new bullet lists.
The new bullet sections (supported conversions, what cannot convert, version-specific notes, best practices) need ✅❌🔴🟡
⚠️ prefixes for scannability.
As per coding guidelines, "Use emojis (✅❌🔴🟡⚠️ ) in documentation for scannability".
899-904:⚠️ Potential issue | 🟡 MinorFix missing space in field description.
The
ConversionResult.Documentdescription renders as “OAS2Document orOAS3Document”. Add a space for readability.✅ Suggested fix
-| `Document` | `any` | Converted document (*OAS2Document or*OAS3Document) | +| `Document` | `any` | Converted document (*OAS2Document or *OAS3Document) |MIGRATION_V1.12_TO_V1.13.md (2)
1-543: 🧹 Nitpick | 🔵 TrivialEnhance scannability with emojis per coding guidelines.
As per coding guidelines, documentation should use emojis (✅❌🔴🟡
⚠️ ) for scannability. Consider adding emojis to major section headers to improve visual navigation.💅 Suggested emoji additions
Examples for key sections:
-## Overview of Changes +## 📋 Overview of Changes -## Breaking Changes +## ⚠️ Breaking Changes -### Removed Functions +### ❌ Removed Functions -## Migration Examples +## 🔄 Migration Examples -## Benefits of the New API +## ✅ Benefits of the New API -## Migration Strategy +## 🗺️ Migration Strategy -## Getting Help +## 💬 Getting Help -## Summary +## 📝 SummaryBased on learnings, the coding guidelines specify: "Use emojis (✅❌🔴🟡
⚠️ ) in documentation for scannability."
1-543:⚠️ Potential issue | 🟡 MinorAdd emojis to documentation for scannability per markdown guidelines.
This migration guide documents real, implemented API changes (the
*WithOptionsfunctional options API is actively used throughout the codebase in tests, examples, and the CLI). The file is appropriately included in this documentation improvement PR and correctly located at the repository root.However, it violates the coding guideline: "Use emojis (✅❌🔴🟡
⚠️ ) in documentation for scannability." Add relevant emojis throughout the guide (e.g., ✅ for what's new in v1.13.0, ❌ for removed functions, 🔴 for breaking changes) to improve visual scannability as documented in the project guidelines.
🤖 Fix all issues with AI agents
In @.claude/agents/benchmark-analyzer.md:
- Line 72: Remove the stray markdown blockquote markers ('>') that appear as
lone lines in .claude/agents/benchmark-analyzer.md (specifically the standalone
'>' occurrences around the section near line 72, and similar markers at the
nearby lines you noted), leaving normal paragraph/section text intact so the
markdown renders correctly.
In @.claude/skills/prereview/SKILL.md:
- Line 30: The phrase "2. **Commit staged only** - Commit only what's currently
staged" repeats "only"; update the markdown in .claude/skills/prereview/SKILL.md
replacing that line with a clearer wording such as "2. **Commit staged changes**
- Commit what's currently staged" (or "2. **Commit staged only** - Commit just
the staged changes") to remove the redundant adverb while preserving the
original meaning.
In @.markdownlint-cli2.yaml:
- Around line 24-31: Add the docs/plans exclusion to the markdownlint globs:
update the globs array in .markdownlint-cli2.yaml (the block containing
"**/*.md" and the current negated patterns) to include a new negation entry
"!docs/plans/**" so planning documents are skipped; ensure the new entry follows
the same pattern as other exclusions like "!docs/packages/**".
In `@docs/cli-reference.md`:
- Around line 226-230: This edit was made to a generated docs file; instead
update the source doc at the repository root (the canonical CLI reference
source), change the example that maps Map[string,int] to use the desired forms
(e.g., the 'underscore' example Map_String_Int_ and the 'of' example
MapOfStringOfInt) in that source file, then regenerate the docs so
docs/cli-reference.md is rebuilt; also search for and update any other generated
occurrences of the same examples (the other places showing 'underscore'/'of'
multi-parameter type examples) in the source before regenerating.
In `@Makefile`:
- Around line 168-176: The lint-md target currently runs "npx markdownlint-cli2"
unconditionally and will fail make check on machines without Node/npm; modify
the lint-md Makefile target to first detect Node or npm (e.g., using command -v
node or command -v npm) and, if missing, print a clear message and skip markdown
linting (exit 0) just like the existing lint target checks for golangci-lint,
otherwise run npx markdownlint-cli2; keep the target name lint-md and the check
dependency on lint-md unchanged so developers without Node won't break make
check.
…pipeline - Standardize Homebrew install to single-command form across all docs - Update MCP tool count from 15 to 17 (walk_headers, walk_refs from #321) - Add missing walk tool docs (group_by, offset, resolve_refs fields) - Add Prerequisites section to mcp-server.md with install instructions - Fix CLAUDE.md: docs/ is mixed source + generated, not all generated - Soften emoji guidance to reduce CodeRabbit false positives - Add markdownlint-cli2 with practical config (.markdownlint-cli2.yaml) - Add lint-md Makefile target, integrated into make check - Auto-fix 845 markdown spacing violations across 70 files - Fix 2 structural markdown bugs (broken table pipes, skipped heading) - Rewrite .claude/docs/docs-website.md with complete file mapping - Add docs commands to .claude/docs/make-commands.md - Remove stale .gitignore and docs-clean entries for files no longer generated - Add docs/examples to docs-clean target (was missing) - Remove 40 completed plan files from docs/plans/ Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
erraggy
force-pushed
the
docs/fix-docs-accuracy-and-pipeline
branch
from
55689da to
7f65d8e
Compare
Review Round 2 — Response to all 21 comments5 In-diff actionable comments
16 Outside-diff-range comments13 emoji comments (all dismissed): These all reference the stale CodeRabbit learning "Use emojis in documentation for scannability." This guideline was updated in this very PR — CLAUDE.md now says "Emojis welcome in PR descriptions and release notes, but not required in code or docs." The learning needs to be refreshed. Affected files:
All fixes pushed in commit 7f65d8e. |
1 participant
Summary
docs/plans/Changes
Documentation accuracy
brew install erraggy/oastools/oastools(was two-stepbrew tap && brew installin 4 files)docs/index.md,docs/mcp-server.md,docs/claude-code-plugin.md(reflects walk_headers + walk_refs from feat(mcp): add group_by aggregation, walk_headers, walk_refs, and usability improvements #321)walk_headers,walk_refs,group_byaggregation,offset,resolve_refscommon fieldsdocs/mcp-server.mdwith installation instructionsBuild pipeline cleanup
docs/is mixed source + generated (was incorrectly "all generated").claude/docs/docs-website.mdwith complete source vs generated file mapping, all make commands, deployment info, and historical note on PR docs: redesign README and docs site for clarity #314 transition.claude/docs/make-commands.md.gitignoreentries for docs copies no longer generated (AGENTS.md, WORKFLOW.md, CLAUDE.md, RELEASES.md, BENCHMARK_UPDATE_PROCESS.md)docs-cleanMakefile target lineHousekeeping
docs/plans/(~21K lines)Context
PR #321 added
walk_headers,walk_refs, andgroup_byaggregation to the MCP server but only updatedplugin/CLAUDE.md(AI-facing). Human-facing docs were stale. PR #314 changeddocs/index.mdfrom generated (copied from README.md) to hand-crafted, but the CLAUDE.md guidance and deep dive docs weren't updated to reflect the new model.Testing
scripts/prepare-docs.shconfirmsdocs/index.mdis hand-crafted (line 23)tools_walk_*.gofiles).goreleaser.yamlconfirms Homebrew tap configuration🤖 Generated with Claude Code