fix(docs): align guides with generated api#95
Merged
Conversation
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
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.
Problem
Guides and committed API docs carried pre-existing naming/link drift that PR #94 made highly visible:
MeshShaderclass the engine no longer exports — the current API isShaderSource+MeshMaterial./api/mesh-shader/page.core-concepts/application.mdxlinked four options interfaces that get no generated API pages.SourceSnippet.astrohad two pre-existingastro checktype errors.apiLinkswere validated but never shown in the chapter UI.Solution
custom-mesh-shaderschapter onto the realShaderSource+MeshMaterial+new Mesh({ material })API (its construction/attach blocks are now standalone-typechecked instead ofno-check), and fixed every prose/table/label reference incustom-mesh-shaders,backend-comparison,custom-renderers,filters, andrender-pipeline-debugging(the WebGPU debug label now matches the realMeshMaterial (custom)). Prose now distinguishes shader source / material / renderer correctly;detectUniformDrift()is attributed toShaderSource./api/mesh-shader/links now resolve to/api/mesh-material/(andShaderSource.detectUniformDrift()→/api/shader-source/#methods). The four*ApplicationOptions/LoaderOptionslinks are demoted to inline code: the generator documents only classes/enums, so interfaces never get pages, and a four-type generator special case is explicitly out of scope (Option C).SourceSnippet.astroderives thelanguageprop from the<Code>component's ownlangtype (noany, no deep import) and usesAstro.url.pathnamefor error context instead of the untypedAstro.self.moduleId.astro checkis now 0 errors.Gradientvalue-object members andGraphicsfill/stroke styles), is byte-identical across runs, and is committed so a fresh build leaves the tree clean.apiLinks(build-validated against the api collection, only when present); curatedTryItblocks stay for playground + API combos.test/site/guide-prose-links.test.tsvalidates internal/api/and/guide/links in MDX prose,NextStephrefs, andTryItslugs — with locale / base / trailing-slash / hash / query normalization — and guards against the removedmesh-shaderand options-interface pages.Scope
Docs / site / tooling only. No runtime features, no API changes, no new examples or templates, no playground redesign, no versioning or release.
Validation
All green from a clean tree, and the tree stays clean after API regeneration + build + site build:
pnpm typecheck·typecheck:guides(28 extracted / 20 no-check, up from 26 / 22) ·typecheck:examples— passpnpm lint:strict— passpnpm test— 1846 pass (incl. the new link-drift test)pnpm build·verify:exports·verify:package·verify:create-exo-app(45 pass) — passpnpm site:build(572 pages) ·test:examples:smoke(118 pass) ·astro check(0 errors) — passgit status --shortis clean after generate + build + site:build (only the intended 21 files)pnpm format:checkflags 6 files (rollup.config.ts,scripts/extract-guide-snippets.ts,scripts/verify-create-exo-app.ts,test/site/example-search.test.ts,test/site/source-snippets.test.ts,tsconfig.guides.json) — all unmodified by this PR and pre-existing onmain(prettier drift). Left untouched to avoid mixing unrelated reformatting into a docs PR; recommend a dedicated formatting/prettier-pin PR.Release note
Release preparation must be recreated fresh from
mainafter this PR. The stale release-prep PR #93 is superseded by #94 and this PR and can then be closed. This PR intentionally does not touch versioning or the changelog.