✨ Show experimental APIs on the API docs#1203
Closed
taras wants to merge 3 commits into
Closed
Conversation
Surface symbols exported from the package's `./experimental` entrypoint in the API Reference section of the docs site: - `/api` index lists experimental symbols inline (alphabetically) with an "experimental" badge, linking to a namespaced page. - Experimental symbol pages live at `/api/:series/experimental/:symbol` and render an "Experimental" banner; their sidebar lists stable + experimental symbols with badges, resolving each link to the correct (flat vs namespaced) URL via root-based resolution. - Stable pages, older series (v3), and the version toggle are unaffected. The "experimental" signal is entrypoint membership (the `./experimental` export key), carried as `DocPage.experimental` and set in `package.ts`. Also upgrades `@deno/doc` 0.188.0 -> 0.199.0 and `@deno/graph` 0.89.0 -> 0.100.1, which required migrating the docs pipeline from the v1 flat `DocNode[]` model to the v2 `Document`/`Symbol`/`Declaration` model (name moved onto `Symbol`, `.def` replaces per-kind def fields, `TsType*Def` payloads renamed to `.value`, `NamespaceDef.elements` is now `Symbol[]`). Note: `@deno/doc` 0.200.0-0.202.0 ship broken wasm bindings that fail to instantiate under Deno (`__wbindgen_placeholder__`), so 0.199.0 is the newest usable v2 release. Aligns www CI to Deno v2.9.1 (matching #1202).
commit: |
The /api index was pulling experimental symbols from v4-next and listing them inline under the stable v4 (4.0.3) heading, implying 4.0.3 shipped them. Source each section's experimental group from that section's own series (`docs.v4["./experimental"]`), so the index only shows experimental APIs the displayed release actually exports (none for 4.0.3 today; auto-appears when a stable release exports `./experimental`). The prerelease's experimental APIs remain reachable via the "4.1.0-alpha.9 also available" link — those symbol pages' sidebars already list them, badged.
The sidebar version toggle on symbol pages only listed stable series (3.6.1, 4.0.3) and excluded prereleases. Include the prerelease as a "next" entry when it's newer than its stable parent and documents the current symbol. Also determine the active toggle entry from the page's own series (via `seriesName`) instead of `major(pkg.version)`, which previously mis-bolded the stable version on prerelease (v4-next) pages.
Member
Author
|
Superseded by a 2-PR stack that separates concerns:
Same net change as this PR, split for reviewability. |
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.
Closes #1200.
Surfaces symbols exported from the package's
./experimentalentrypoint (e.g.createApi,api) in the API Reference section of the docs site.What you'll see
/apiindex — experimental symbols appear inline in the alphabetical list with anexperimentalbadge, linking to their namespaced page. Stable symbols are unchanged/unbadged./api/:series/experimental/:symbol(e.g./api/v4-next/experimental/createApi) renders an "Experimental" banner above the header. The sidebar lists all symbols for that series; experimental ones are badged, and each link resolves to the correct URL (stable →/api/:series/:symbol, experimental →/api/:series/experimental/:symbol)./api/v4/run), v3, the version toggle, and search all behave as before. Sitemap/Pagefind pick up the new pages automatically.The "experimental" signal is entrypoint membership (the
./experimentalexport key), carried asDocPage.experimentaland set once inwww/lib/package.ts. No@experimentalJSDoc tag is used (it isn't native to@deno/doc). Experimental docs currently only exist in v4-next (the stable v4.0.3 tag predates the/experimentalexport); all rendering no-ops gracefully for series without that entrypoint.Dependency upgrade + migration
Bumps
@deno/doc0.188.0 → 0.199.0and@deno/graph0.89.0 → 0.100.1. This required migrating the docs pipeline from the v1 flatDocNode[]model to the v2Document/Symbol/Declarationmodel:doc()now returnsRecord<url, Document>;Document.symbolsgroup declarations by name (namemoved ontoSymbol)..defreplaces per-kind def fields (functionDef/classDef/…);ClassMethodDef.def; everyTsType*Defpayload renamed to.value;NamespaceDef.elementsis nowSymbol[].DocNodeis re-defined locally asDeclaration & { name }inuse-deno-doc.tsx.Also aligns
wwwCI to Deno v2.9.1 (the only workflow still on 2.6.1; matches #1202).Validation
Ran the site locally (
deno task dev) and verified end-to-end:/api→ 2 experimental badges onapi/createApi, linking to/api/v4-next/experimental/*./api/v4-next/experimental/createApi→ banner present, sidebar mixes stable (flat links) + experimental (namespaced links), correct title./api/v4/run(stable) &/api/v3/run→ no badges/banner/experimental links./api/v4-next/run→ experimental symbols badged in sidebar, no banner./api/v4/call): Parameters, Return Type, and type references render correctly.deno fmt --check,deno lint, anddeno check main.tsxall pass.