Demo: SDK Reference product (10-SDK polyglot reference)#337
Draft
Devon-White wants to merge 10 commits into
Draft
Demo: SDK Reference product (10-SDK polyglot reference)#337Devon-White wants to merge 10 commits into
Devon-White wants to merge 10 commits into
Conversation
Adds a new top-level Fern product (SDK Reference) that hosts
auto-generated reference docs for every SignalWire SDK as variants
of a single Reference tab: TypeScript, Python, Ruby, Go, Java, .NET,
PHP, Rust, C++, Perl.
Showcase of the sdk-ref-docs polyglot pipeline. Content lives in
fern/products/sdk-reference/<language>/ and is wired via the standard
folder: pattern (modeled on server-sdks.yml), so reviewers can browse
all pages directly on GitHub.
Generator-owned: every .mdx page carries auto_generated: true in
frontmatter and will be rewritten on the next pipeline run.
Hand-written in this PR:
- fern/docs.yml — one product entry added
- fern/products/sdk-reference/sdk-reference.yml — variants + folder
layout for the 10 SDKs
Known gaps (renderer-side, follow-up):
- Some auto-fenced docstring blocks are visually rendered as prose
rather than monospace because the renderer's fence-aggregation
heuristic only triggers when every line in the paragraph is
indented. Content is correct and MDX-safe; styling will improve as
the heuristic is generalized.
Contributor
Per the Fern variant model (see server-sdks.yml), page slugs must be relative to the product slug and must include the tab segment so the URL resolves as /docs/<product>/<tab>/<variant>/<page>. Our slugs were including the product prefix (/sdk-reference/...), which Fern was prepending /sdk-reference/ to anyway, producing the doubled path /sdk-reference/sdk-reference/typescript/... and leaving the intended variant URLs (/sdk-reference/reference/<lang>) as 404s. Regenerated with base_slug: /reference/<lang> so each page now emits slug: /reference/<lang>/<page> and resolves at the right Fern URL. Also adds explicit slug: dotnet and slug: cpp to the .NET and C++ variants so Fern's title-derived auto-slugs don't produce paths with problematic characters (`.net`, `c++`).
Pipeline-side changes pulled in across all 10 SDKs:
* LanguageSpecific schema (modifiers, typeParameters, extends, implements,
mixins, decorators, throws, yields, seeAlso, since, overloads). All 10
extractors populate the cross-language keys plus per-language extras.
* Five new built-in sections: Modifiers, Type Parameters, Throws,
Inheritance, See Also. Wired into the default section order.
* Overload grouping via Item.signatures[] + languageSpecific.overloads[].
Java / C++ / .NET / TS now collapse multi-overload methods onto one
page with per-overload Parameters/Returns subsections and titled
<CodeBlocks> tabs (Overload 1 / Overload 2 / ...).
* Multi-example pages get titled tabs (Example 1 / Example 2 / ...).
* Producer scripts emit additional fields:
- yard-dump.rb: @example/@raise/@deprecated/@yield/@option/attr_type/
mixins/scope, with dedupe of #/. method double-emission.
- SignalwireDoclet.java: type_parameters, annotations, thrown_types,
modifiers as a structured array (was space-joined string).
- godoc-dump: Example_* test fns, struct field tags/docs/embedded
markers, generic type parameters.
- php-dump.php: PHP 8 #[Attribute]s, traits, enum cases, abstract/
final modifiers on classes and methods.
- perl-dump.pl: @ISA/use parent/Moose extends/with/has, @export*,
use constant. EXCEPTIONS section emits {type,description} pairs.
Rendering-side fixes:
* TS @example bodies preserve source indentation (was flattening every
line to column 0 via partsToText's wrap-continuation regex).
* Rust impl-Trait walk: 59 types now show their trait implementations
under Inheritance > Implements; blanket impls and synthetic auto-
derive markers filtered out so the method list isn't polluted by
From::from / Into::into / Borrow::borrow.
* .NET overload grouping: matchKey strips the param list DocFX bakes
into `name` so true overloads collapse onto one page.
* Go interface method signatures no longer concatenate as Getfunc(...).
* C++ duplicate header+impl signature emission deduped inside
groupOverloads.
* Regex stability pass: dead fallback parsers removed (Python
parseDocSections, Go DEPRECATED_RE, .NET [Obsolete()] syntax-content),
TS @throws stops guessing type-vs-description, Perl exceptions parsed
on the producer side, Java modifiers shape is now a structured array.
Net: 4662 files changed across 10 SDKs (+16,608 / -23,781). The deletes
come from overload-collapsed pages and blanket-impl method filtering.
Full clean regeneration of the SDK reference trees (removed the prior generated docs, rendered all 10 languages from fresh dumps): typescript, python, ruby, go, java, perl, php, dotnet, cpp, rust. Includes fixes surfaced during this regen: java host-dump (bash 3.2 empty-array), php stale-cache, rust stale dump-file pickup.
Regenerate all 10 SDK trees with platform: fern / format: mdx — Fern MDX components (ParamField, CodeBlocks) and .mdx pages, replacing the prior plain .md output. Nested per-module layout. Content unchanged (fresh dumps from real SDK source).
Regenerate all 10 SDK trees with the generator MDX fixes: docstring-derived
HTML (<name>, List<String>, <see>, <p>) is escaped so MDX 3 no longer parses
it as JSX, and Python sentinel/expr defaults no longer emit a broken
default={}. Verified: all 14,587 .mdx files parse cleanly under the MDX-JSX
micromark parser (0 failures).
Python and PHP source URLs had a phantom /src segment and a double slash (blob/main//src/...) because griffe/PHP-reflection report absolute paths under the container's /src bind-mount. Regenerated with the path fix.
dotnet now has source links (DocFX git features enabled), php emits repo-relative paths with property/constant links, go packages/methods get source. python output unchanged (already correct).
The C++ extractor mapped Doxygen's synthetic `@<digits>` names for
anonymous `namespace { ... }` blocks to module pages, producing 14 empty,
garbage-titled pages (file-local internal-linkage symbols, never public
API). Fixed upstream in lustri (extractor skips `@`-segment compounds).
Removes the 14 anonymous-namespace pages and updates the parent namespace
indexes + _meta.json to drop the references.
Java now dumps via a JavaParser source parse instead of javadoc+gradle (see
lustri feat/java-source-parser-dumper). Same public surface (1774 items), with:
- Types in clean source form (List<Section>) instead of fully-qualified
(java.util.List<com.signalwire.sdk.pom.Section>) — consistent with the
other SDKs. This is the bulk of the diff.
- Method/@param descriptions at full parity (541 summaries, 70 @param, 76
return descriptions), including AgentBase.defineTool's full docs which the
initial dump had dropped (orphaned-javadoc bug, since fixed).
Java-only change; no other SDK touched.
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.
What
Adds a new top-level Fern product, SDK Reference, that hosts auto-generated reference docs for every SignalWire SDK as variants of a single Reference tab:
TypeScript · Python · Ruby · Go · Java · .NET · PHP · Rust · C++ · Perl
Why
Showcase of the
sdk-ref-docspolyglot doc pipeline. Same canonical Bundle → renderer flow as the committeddocs/selfdoc/tree in that repo, but pointing all 10 SDK extractors at this docs repo'sfern/products/sdk-reference/directory.What's in the diff
Hand-written (2 files):
fern/docs.yml— one product entry added under existing column structurefern/products/sdk-reference/sdk-reference.yml— variants + folder layout for the 10 SDKs, modeled onfern/products/server-sdks/server-sdks.ymlGenerator-owned (14,608 files under
fern/products/sdk-reference/<language>/):.mdxpage carriesauto_generated: truein frontmatter/sdk-reference/<language>/...Companion changes upstream
Two narrow renderer fixes shipped to
sdk-ref-docsto make the output Fern-safe:htmlAttrnow escapes&,<,>,"— Java's<init>constructors no longer break JSX attributesmdxSafeProsefilters CommonMark indented-code ranges so JSX/expression escaping reaches Javadoc HTML and Python docstring fragments that MDX wouldn't otherwise honor as codeValidation
yarn fern-checkpasses (0 errors, 1 pre-existing color-contrast warning)sdk-ref-docsKnown gaps (renderer-side follow-ups, not blockers)
fa-regular fa-codefor SDKs without a Font Awesome brand glyph (Go, Perl, C++).Test plan
yarn fern-checkcleanyarn dev(oryarn start:dev) renders SDK Reference in the top nav