Upgrade Weave TS SDK docs generation to TypeDoc 0.28 and regenerate - #2949
Draft
dbrian57 wants to merge 2 commits into
Draft
Upgrade Weave TS SDK docs generation to TypeDoc 0.28 and regenerate#2949dbrian57 wants to merge 2 commits into
dbrian57 wants to merge 2 commits into
Conversation
Bumps typedoc 0.25.13 → 0.28.20 and typedoc-plugin-markdown 3.17.1 →
4.12.0, and regenerates the TypeScript SDK reference from weave
v0.53.2-ts. The old pins no longer worked: TypeDoc 0.25 rejects the
TypeScript 5.9 the Weave SDK now uses, and aborts on an upstream type
error in weave's googleAdk integration (skipErrorChecking now set,
since docs generation doesn't need the project to type-check).
Pipeline updates for the plugin's v3 → v4 output format:
- hidePageHeader added alongside hideBreadcrumbs; kind-prefixed titles
("Function: login()") cleaned when building frontmatter
- new variables/ directory handled in link rewriting and nav
- deprecation hoisting handles v4's "## Deprecated" heading sections,
page-level warnings hoist to the top of the page, and inserts are
MDX-safe after frontmatter
- prose sanitizer escapes raw <, {, } that TypeDoc copies verbatim from
third-party .d.ts comments (@google/adk ships a corrupted doc comment
that 0.28 inherits onto WeaveAdkPlugin via its implements clause)
Notable content changes: type-only class exports (Conversation, LLM,
SubAgent, Tool, Turn, WeaveClient) are now correctly documented as
interfaces since consumers can't construct them; the deprecated
Session-era exports move from functions/ to variables/; deprecated
symbols get strikethrough index entries. English nav in docs.json
updated to match; localized navs are left to the locadex sync.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
HiveMind Sessions1 session · 50m · $22
ScreenshotsView all sessions in HiveMind → Run |
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Contributor
📚 Mintlify Preview Links✨ Added (10 total)📄 Pages (10)
📝 Changed (80 total)📄 Pages (79)
⚙️ Other (1)
🗑️ Deleted (9 total)View deleted files📄 Pages (9)
🤖 Generated automatically when Mintlify deployment succeeds |
Contributor
🔗 Link Checker ResultsPreview: https://wb-21fd5541-typedoc-upgrade.mintlify.site |
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
…ag selection
Review feedback on the preview surfaced formatting regressions from
typedoc-plugin-markdown v4:
- Optional members were marked twice: a trailing ? on the heading and
bold name ("display_name?") plus an `optional` tag in the signature.
Keep the tag, drop the ?. Function-parameter headings ("host?") keep
theirs — there the ? is the only optionality marker.
- v4 places "Defined in:" between the signature and the description,
pushing the description below the metadata. Source links now move to
the end of their block, restoring the signature → description →
source reading order the docs had before.
Also fixes latent tag selection in download_weave_source: "latest" took
the highest v* tag, so weave's Python releases (v0.53.4) outsorted the
TS SDK's -ts tags and the docs silently regenerated from a commit with
unreleased TS APIs. Only vX.Y.Z-ts tags are considered now.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
Readability impactWord-weighted Flesch-Kincaid grade change across 24 changed pages: -7.0 (easier). Lower Flesch-Kincaid grade and higher reading ease both mean easier to read. This check is informational and never blocks a PR. Human readability
AI agent comprehensionRated 0-3 (higher is easier for an agent to parse and act on).
Pages showing — could not be rated: Unterminated string starting at: line 1 column 221 (char 220) Curated-docs baseline median FK grade by type: conceptual 10.5, procedural 8.8, reference 9.4. |
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.
Description
Upgrades the TypeScript SDK reference pipeline from
typedoc@0.25.13+typedoc-plugin-markdown@3.17.1totypedoc@0.28.20+typedoc-plugin-markdown@4.12.0, and regenerates the reference from weavev0.53.2-ts.The upgrade was required, not just nice-to-have — the old pins no longer work: TypeDoc 0.25 rejects the TypeScript 5.9 the Weave SDK now uses, and aborts on an upstream type error in weave's
googleAdkintegration (duplicate@google/genaiversions in its dependency tree). The config now setsskipErrorChecking, since docs generation doesn't need the project to type-check.Script changes (
scripts/reference-generation/weave/generate_typescript_sdk_docs.py)The markdown plugin had a major rewrite in v4, so the post-processing needed updates:
hidePageHeaderadded alongsidehideBreadcrumbs; v4's kind-prefixed page titles (Function: login(),~~Variable: startSession~~) are cleaned when building frontmatter.variables/output directory is handled in link rewriting and added to the nav.## Deprecatedheading sections (levels H2–H5 depending on nesting). Page-level deprecations hoist to the top of the page; member-level ones anchor under the member heading.<,{,}in prose. TypeDoc 0.28 inherits doc comments throughimplementsclauses, and@google/adkships a corrupted doc comment in its published.d.tsthat would otherwise break the MDX build. (The garbage text onWeaveAdkPlugin.onToolErrorCallbacknow renders as harmless literal text; the real fix belongs upstream in ADK.)Content changes worth knowing about
Conversation,LLM,SubAgent,Tool,Turn,WeaveClient). Weave exports them viaexport type { ... }— consumers can name but never construct them — so 0.28's rendering is more accurate than 0.25's constructible-class pages. Six pages movedclasses/→interfaces/.startSession/endSession/getCurrentSessionconst re-exports moved fromfunctions/to a newvariables/group, and deprecated symbols get strikethrough index entries.Sessiontype aliases are now disambiguated (session,session-1).docs.jsonupdated to match. Localized navs were deliberately left alone — the locadex automation owns fr/ja/ko and will catch up after merge; runningsync_localized_navigation.pyhere produced a ~2,300-line unrelated diff.Testing
mint validate)