feat(docs): auto-generate driftable doc sections (supersedes #851)#873
Merged
feat(docs): auto-generate driftable doc sections (supersedes #851)#873
Conversation
Extend generate-docs-sections.ts with 7 new marker-based sections that eliminate documentation drift by generating content from source code: - README.md: dev prerequisites (Bun version from packageManager), library prerequisites (Node version from engines.node), dev scripts - contributing.md: dev prerequisites - DEVELOPMENT.md: env var table (from env-registry.ts devGuide tags) - self-hosted.md: env var table (from env-registry.ts selfHosted tags) - getting-started.mdx: platform support table (MDX marker syntax) Source-of-truth additions: - Add SENTRY_RELEASE to env-registry.ts (used by propose-version but missing from auto-generated configuration.md) - Add selfHosted/devGuide tags to env-registry entries for table generation Content additions (hand-written fragments, the correct mechanism): - release.md: bash examples for release delete and release deploys - event.md: full event list examples section CI: add README.md and getting-started.mdx to the check-generated git-diff and auto-commit lists. Supersedes #851 (manual fixes) with structural automation.
Contributor
|
Contributor
Codecov Results 📊✅ 6289 passed | Total: 6289 | Pass Rate: 100% | Execution Time: 1ms 📊 Comparison with Base Branch
✨ No test changes detected All tests are passing successfully. ✅ Patch coverage is 100.00%. Project has 13051 uncovered lines. Coverage diff@@ Coverage Diff @@
## main #PR +/-##
==========================================
+ Coverage 75.94% 75.99% +0.05%
==========================================
Files 294 294 —
Lines 54371 54363 -8
Branches 0 0 —
==========================================
+ Hits 41289 41312 +23
- Misses 13082 13051 -31
- Partials 0 0 —Generated by Codecov Action |
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
1 participant
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.
Summary
Extend
generate-docs-sections.tswith 7 new marker-based sections that eliminate documentation drift by auto-generating content from source code. Also adds missingSENTRY_RELEASEto the env var registry and hand-written examples forrelease delete/deploysandevent list.Supersedes #851 with structural automation instead of manual patching (same relationship as #739 → #724).
What's auto-generated now
README.md,contributing.mdpackageManagerinpackage.jsonREADME.mdengines.nodeinpackage.jsonREADME.mdDEVELOPMENT.mdenv-registry.tsentries withdevGuidetagself-hosted.mdenv-registry.tsentries withselfHostedtaggetting-started.mdxALL_TARGETSinbuild.tscontributing.mdDEVELOPMENT.md,self-hosted.mdOAUTH_SCOPESarrayWhat was wrong with #851
SENTRY_CUSTOM_HEADERSformat was documented as comma-separatedkey:value— the actual code (src/lib/custom-headers.ts) uses semicolon-separatedName: Valuepairs. Would have shipped incorrect docs.DOCUMENTATION_AUDIT.mdat repo root — a 162-line audit report that becomes stale immediately.generate:docsoverwrites the manual changes.Changes
Source-of-truth additions
SENTRY_RELEASEadded toenv-registry.ts(flows into auto-generatedconfiguration.md)selfHostedanddevGuidetags added toEnvVarEntrytype and relevant entriesGenerator extensions (
script/generate-docs-sections.ts){/* GENERATED:START */}syntax for.mdxfiles)dev-prereq: Bun version frompackageManagerfieldlibrary-prereq: Node version fromengines.nodedev-scripts: Curated script list with descriptionsdev-env-vars: Table from registry entries taggeddevGuideself-hosted-env-vars: Table from entries taggedselfHosted, with cross-validationplatform-support: Platform/architecture tableFragment additions (hand-written, as designed)
release.md: Examples forrelease delete(with--yes,--dry-run) andrelease deploysevent.md: Full "Listing Events" section with query, full, period, pagination, JSON examplesCI
README.mdandgetting-started.mdxadded tocheck-generatedgit-diff and auto-commit lists