docs: documentation audit — fix gaps between code and docs#724
Closed
cursor[bot] wants to merge 1 commit intomainfrom
Closed
docs: documentation audit — fix gaps between code and docs#724cursor[bot] wants to merge 1 commit intomainfrom
cursor[bot] wants to merge 1 commit intomainfrom
Conversation
- Add missing commands to README table (release, repo, team, trial) - Add yarn to README package manager examples - Add Node.js >=22 note for npm users - Fix OAuth scope lists: add missing team:write in DEVELOPMENT.md and self-hosted.md - Add undocumented env vars to configuration.md (SENTRY_FORCE_ENV_TOKEN, SENTRY_OUTPUT_FORMAT, SENTRY_MAX_PAGINATION_PAGES, SENTRY_INIT) - Update contributing.md project structure to reflect all 15+ command directories - Add Cursor support to agentic-usage.md alongside Claude Code - Document installer flags and SENTRY_INIT in getting-started.mdx - Add DOCUMENTATION_AUDIT.md with full gap report Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Contributor
Semver Impact of This PR🟢 Patch (bug fixes) 📋 Changelog PreviewThis is how your changes will appear in the changelog. Bug Fixes 🐛Upgrade
Other
Documentation 📚
Internal Changes 🔧
🤖 This preview updates automatically when you update the PR. |
Contributor
|
Contributor
Codecov Results 📊✅ 134 passed | Total: 134 | Pass Rate: 100% | Execution Time: 0ms 📊 Comparison with Base Branch
✨ No test changes detected All tests are passing successfully. ✅ Patch coverage is 100.00%. Project has 1601 uncovered lines. Coverage diff@@ Coverage Diff @@
## main #PR +/-##
==========================================
- Coverage 95.30% 95.29% -0.01%
==========================================
Files 232 232 —
Lines 33993 33992 -1
Branches 0 0 —
==========================================
+ Hits 32395 32391 -4
- Misses 1598 1601 +3
- Partials 0 0 —Generated by Codecov Action |
Member
|
Superseded by #739, which addresses the same gaps with auto-generation infrastructure instead of manual fixes. |
BYK
added a commit
that referenced
this pull request
Apr 13, 2026
## Summary Eliminates documentation drift by auto-generating content from source code. Replaces #724 with a structural fix instead of manual patching. - **configuration.md**: Env var reference now generated from `src/lib/env-registry.ts` using the existing fragment pattern. Adds 6 previously undocumented env vars. - **contributing.md**: Project structure tree generated from Stricli route tree via `GENERATED:START/END` markers (was listing 5 command dirs, now correctly shows 15+). - **DEVELOPMENT.md & self-hosted.md**: OAuth scopes generated from exported `OAUTH_SCOPES` array (fixes missing `team:write`). - **README.md**: Removed driftable commands table, replaced with pointer to docs site. ## Why PR #724 identified real documentation gaps (missing commands in README, missing `team:write` in OAuth scopes, 6 undocumented env vars, stale project structure). But manually fixing them leaves the same drift problem — the docs will go stale again next time someone adds a command, env var, or OAuth scope. This PR instead makes the documentation self-updating: | Surface | Source of Truth | Generation | |---------|----------------|-----------| | Env var reference | `src/lib/env-registry.ts` | Full-page (fragment pattern, gitignored) | | Project structure | Route tree introspection | Marker injection in committed file | | OAuth scopes | `OAUTH_SCOPES` export from `oauth.ts` | Marker injection in committed files | | README commands | Removed | N/A (points to docs site) | ## New infrastructure - **`src/lib/env-registry.ts`** — Centralized env var metadata catalog (23 entries). Doc-generation data source only, no runtime changes. - **`script/generate-docs-sections.ts`** — Marker-based injection for committed files (`GENERATED:START/END` named markers). Supports `--check` for CI. - **`generate-command-docs.ts`** extended to also produce `configuration.md` from registry + fragment. - CI `check:docs-sections` validates markers aren't stale. Auto-commits regenerated files on non-fork PRs. All generators run as part of `bun run generate:docs` (already in `dev`, `build`, `typecheck`, `test` chains). Closes #724
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation Audit
Full cross-reference of the Sentry CLI implementation against all documentation surfaces (README, docs site, DEVELOPMENT.md, contributing.md). The detailed audit report is in
DOCUMENTATION_AUDIT.md.Changes
README.md
release,repo,team,trialeventdescription from "View event details" → "List and view event details" (event list exists)yarnto package manager install examplesDEVELOPMENT.md
team:writescopedocs/src/content/docs/self-hosted.md
team:writeto the token creation instructionsdocs/src/content/docs/configuration.md
SENTRY_FORCE_ENV_TOKEN,SENTRY_OUTPUT_FORMAT,SENTRY_MAX_PAGINATION_PAGES,SENTRY_INIT,SENTRY_CLI_NO_AUTO_REPAIR(first 4)docs/src/content/docs/contributing.md
docs/src/content/docs/agentic-usage.md
npx skills addwith actual Claude Code plugin install commandssentry cli setupdocs/src/content/docs/getting-started.mdx
--no-modify-path,--no-completions,SENTRY_INSTALL_DIR,SENTRY_INITDOCUMENTATION_AUDIT.md (new)