Repository navigation
Add Go support to aspire docs api - #21173
Conversation
Index and browse the Go API reference alongside C# and TypeScript. Go uses the same module -> symbol -> member route layout as TypeScript, so the sitemap parser recognizes /reference/api/go routes and the index builder shares one module-based item builder between the two languages. The index schema version is bumped so caches built before Go routes existed are rebuilt. Go routes only appear once the docs site publishes them, so this is safe to ship ahead of the pages. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 21173Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 21173" |
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
🟢 Approval recommended
The narrowly scoped changes preserve existing indexing behavior and include focused regression coverage, with no identified blocking issues.
No open issues 🎉
What changed in this PR
Adds Go API reference discovery to the CLI as an initial step toward Go AppHost GA, ready for publication of the corresponding documentation.
Changes:
- Adds Go routes and shares module-based indexing with TypeScript.
- Invalidates older indexes through a cache schema bump.
- Adds regression coverage and documents Go scopes and output.
| File | Description |
|---|---|
| tests/Aspire.Cli.Tests/Mcp/ApiDocs/ApiSitemapParserTests.cs | Tests Go routes and prefix filtering. |
| tests/Aspire.Cli.Tests/Mcp/ApiDocs/ApiMemberMarkdownParserTests.cs | Tests parser behavior with Go-shaped content. |
| tests/Aspire.Cli.Tests/Mcp/ApiDocs/ApiDocsIndexServiceTests.cs | Covers Go indexing, retrieval, filtering, and cache migration. |
| src/Aspire.Cli/Documentation/ApiDocs/ApiSitemapParser.cs | Registers the Go sitemap route. |
| src/Aspire.Cli/Documentation/ApiDocs/ApiDocsIndexService.cs | Adds Go indexing and updates cache versioning. |
| docs/specs/cli-output-formats.md | Documents the Go language value. |
| docs/specs/api-docs-commands.md | Documents Go scopes and hierarchy. |
Review effort: Balanced
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
> [!NOTE] > **Works with** microsoft/aspire#21173, the CLI support for `aspire docs api --language go`. Neither PR blocks the other: that PR is safe to land first, because the Go scope stays empty until these pages are published. > > **Needed by** #1923 and #1924, whose links to `/reference/api/go/` resolve only once this PR is on `release/17.0`. ## Summary <!-- Describe what this pull request changes and why. --> Adds a Go API reference at `/reference/api/go/**`, shaped like the TypeScript reference: index, module, item and member pages as HTML and `.md`, with sidebar, search and sitemap entries. This is the first step of Go AppHost GA (microsoft/aspire#21115). The reference goes first because its route and markdown shape is what `aspire docs api` parses from the sitemap. What changes: - **Generator.** `AtsJsonGenerator` gains a Go mode (`--language go`). It ports the Go SDK generator's naming and type rules (PascalCase, `(T, error)` results, trailing `opts ...*XxxOptions`, pointers, `*List[T]`, `*Dict[K,V]`) and reads the same `aspire sdk dump` JSON as the TypeScript mode. - **Pipeline.** `generate-ts-api-json.ps1` takes `-Language typescript|go`. `pnpm update:go-api`, `update-integration-data.ps1` and the normalizer handle Go data. `update-integration-data.yml` stages `src/frontend/src/data/go-modules` and its timeout goes from 45 to 75 minutes, since the job now runs C#, TypeScript and Go passes. - **Data.** 122 modules in `src/frontend/src/data/go-modules/` (5.75 MB), generated from the same package versions as `ts-modules`. - **Site.** `go-*` utilities, a `GoMemberCard` component and `reference/api/go/**` routes, plus registrations in the reference sidebar, search, overview and dev hub. The dev hub gets a `Go API` reference link, so the item count assertion in `dev-layout.spec.ts` goes from 30 to 31. - **Doc text.** Doc comments render through a `GoDocText` component. Backtick spans are styled inline code. An `{@ats-ref}` marker links to the type page, or to the package function page for an extension method, when the target is in the same module, and stays styled code otherwise. The markdown routes keep the code spans and render markers as plain code, without links. CLR generic arity markers are stripped from method names in both. - **Sidebar casing.** The Reference, Deployment and Community topic groups and the Reference overview title use sentence case ("Aspire reference", "Aspire deployment", "Aspire community"), like "Aspire integrations" and "Aspire dashboard". - **Tests.** Generator tests for Go mode, vitest suites for routes, markdown, doc text, search, sidebar and the whole seed (`pnpm test:unit:go-api`), and Playwright specs for Go search and sidebar. Existing cross-language specs also cover Go. The version-dropdown scenario for Go is its own test in `filter-navigation.spec.ts`: the existing test already uses 48 to 75 s of its 120 s budget on `release/17.0` CI, so a fourth iteration would leave little margin. Design notes: - A module is the contributing NuGet package (for example `Aspire.Hosting.Redis`), as in TypeScript. The Go SDK itself is one flat package, so each module page states the import path. - The pages carry no experimental or feature-flag notice. The Go AppHost doesn't require a flag at GA (microsoft/aspire#21106). - The Go code copies the TypeScript route and markdown logic into new files and keeps edits to shared files additive, which limits conflicts with the main to release sync. Consolidating the two is a follow-up on `main`. - The 24 `Aspire.Hosting.Azure.Provisioning.<Service>` proxy packages are left out. They would add 72 MB (1.28x the TypeScript data) and their pins are stale on `release/17.0`. The base `Aspire.Hosting.Azure.Provisioning` package is included. Not in this PR: - `<ApiReference>` Go links and a Go option in the AppHost language switcher. The switcher is hard-wired to `csharp|typescript` and needs Go docs tabs first (microsoft/aspire#21112). - `go-modules` in `merge-main-into-release.sh` `generated_dirs` and its test. Add it after the post-GA swap, when `main` has Go data. - Doc fidelity gaps, listed in the generator README: callback properties on core DTOs render as `func(...any) any`, and foreign enums and hand-written SDK types have no pages. A Go `IApiReferenceExporter` (`aspire sdk export --language go`) would replace the dump-derived signatures. Notes: - The data is 13.x-based until the 17.0 packages publish. The updater's PR uses `--base main`, so refreshing 17.0 data needs a manual run and a `release/17.0` base. - Scheduled runs of the updater on `main` fail at `generate-package-json.ps1:112` (`$_.apiReference` under StrictMode). That is unrelated and untouched here. ## Third-party links and affiliations <!-- List any third-party links added or changed by this pull request and disclose any material affiliation with the linked organizations, such as employment, sponsorship, or ownership. Write "None" if this pull request doesn't add or change third-party links. --> None. No third-party links are hand-written in this PR. The generated Go data carries the same upstream package and doc-comment URLs as the existing `ts-modules` data: 13 distinct hosts, every one already present there. ## Validation <!-- List the checks you ran or explain why validation isn't needed. --> The frontend commands run in `src/frontend` with `CI=1`. The unit, lint and markdown crawl results below are for the final head. The local `pnpm build` and Playwright results are from `d7d7633e41`, before the doc text and sidebar casing commits. CI on the final head `e506f71a33` passed all 17 checks, including the frontend build and the six Playwright shards (desktop, tablet and mobile Chromium, two shards each). - `dotnet test tests/AtsJsonGenerator.Tests/AtsJsonGenerator.Tests.csproj --nologo -v q`: 113 passed. - `pnpm test:unit:go-api`: 211 passed (14 files). - `pnpm test:unit`: 1374 passed, 1 skipped (94 files). - `pnpm lint`: no warnings. - Every Go `.md` route crawled on a local dev server that includes this branch: 3,130 pages (1 index, 122 module, 1,902 item, 1,105 member). All return 200 `text/markdown` with no `{@` markers left and no unbalanced backticks, and the crawled set equals what `getStaticPaths` generates. - `pnpm build`: exit 0 in 16 min 51 s on a 28-core machine, 35,616 pages, internal links valid. The sitemap has 3,130 Go, 19,293 TypeScript and 4,914 C# API URLs. - `pnpm exec playwright test --project=desktop-chromium --retries=0` on the Go specs and the specs extended for Go: 125 passed, 1 skipped. - Full Playwright suite on desktop, tablet and mobile (535, 535 and 531 tests, the three projects running at once on one machine): 524, 488 and 484 passed. 12 tests failed across the three runs. The `dev-layout.spec.ts` hub item count failed in all three and was a real regression from the new `Go API` link; it is fixed in this PR. The other 9 failures were timeouts under that load (`dev-browse`, `filter-navigation`, `gallery-search-contract` and one mobile `dev-layout` test). Every failing test passed when rerun alone with `--workers=1 --retries=0`, and `filter-navigation.spec.ts` passes in full on all three projects after the version-dropdown split. - Full regeneration of all 122 modules through `generate-ts-api-json.ps1 -Language go` and the normalizer matched the checked-in data with 0 diffs. After the Foundry fix below, `Aspire.Hosting` and `Aspire.Hosting.Foundry` were regenerated again: core is byte-identical and Foundry matches the committed file. - `aspire docs api list|search|get` against a local build of this site, using the CLI from microsoft/aspire#21173: `list go` returns 122 modules, `search "redis password" --language go` ranks `go/aspire.hosting.redis/redisresource/withpassword` first, and C# and TypeScript output is identical to the previous CLI. - A review pass found one issue: composite exported values in `Aspire.Hosting.Foundry` (201 `FoundryModels.*` entries) rendered as multi-line JSON, which split markdown bullets across lines. Fixed in the generator with a regression test, and a whole-seed vitest now guards every module. --------- Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
> [!IMPORTANT] > **Depends on:** > > - microsoft/aspire#21173: the CLI change that adds `go` to `aspire docs api`, which these pages document. > - #1917: the Go examples use routes from the Go API reference, which exist on `release/17.0` only once that PR lands. > > Merge this PR after both. ## Summary Documents Go support in `aspire docs api`. The CLI change adds `go` next to `csharp` and `typescript`, so the command reference now lists it wherever the other languages are enumerated. This is part of Go AppHost GA (microsoft/aspire#21115). - **`aspire docs api`, `list`, `get` and `search`:** `go` is added to the language roots, the `--language` values, the scope table (`go`, `go/<module>` and `go/<module>/<symbol>`) and the identifier examples (for example `go/aspire.hosting.redis/addredis`). Each addition sits next to the matching TypeScript text. - **`get-started/aspire-skills.mdx`:** "C# and TypeScript API docs" now includes Go. The Go examples use routes from the Go API reference in #1917. Until that PR lands, these pages describe routes that don't exist on `release/17.0` yet, and the Go scope of `aspire docs api` stays empty. The pages carry no "experimental" wording because they go live at the GA docs swap, when the Go feature flag is removed (microsoft/aspire#21106). Not changed: other "C# or TypeScript" text in the docs (`aspire init --language`, the FAQ, `what-is-aspire` and the agent skill file) is about AppHost languages, not API docs. `whats-new/aspire-17.mdx` doesn't mention `aspire docs api` languages, so there's nothing to update there. ## Third-party links and affiliations None. ## Validation - Opened the seven Go routes used in the examples on a local preview of #1917 and confirmed that each returns 200 as HTML and as its `.md` twin (`go/`, `aspire.hosting`, `aspire.hosting.redis`, `addredis`, `redisresource`, `redisresource/withpersistence` and `aspire.hosting/withreference`). All seven are also in that build's `sitemap-0.xml`. Nonexistent routes return an error on the same server, so a 200 is meaningful. - Compiled the five changed MDX files with the repo's `@mdx-js/mdx`. A deliberately broken snippet is rejected, so the check can fail. Every code fence has a language id. - Checked the added lines against the repo's forbidden-words rules, and ran `git diff --check`: both clean. - Ran the three docs-scanning vitest files: 15 passed. Not run: the full `pnpm lint`, `pnpm test:unit` and a site build. ESLint doesn't lint MDX and the repo has no Markdown linter. Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Sébastien Ros (sebastienros)
left a comment
There was a problem hiding this comment.
Thanks, David. This is a small, clean change with good coverage, and the schema-version bump is the right call. I'm approving with one request: please address the duplicate TypeScript/Go results in an unfiltered search (inline comment on ApiDocsIndexService.cs) before merge. The other comments are minor; they can be small updates before merge or follow-ups.
One more minor point outside the diff: the list scope help text (src/Aspire.Cli/Resources/ApiCommandStrings.resx, ScopeArgumentDescription) and the src/Aspire.Cli/README.md examples still mention only csharp/typescript. A go example would help discoverability (remember UpdateXlf and the .Designer.cs if the resx changes).
- Break API search score ties by language (csharp, typescript, go) so a Go twin no longer outranks its TypeScript counterpart in unfiltered searches, and pin the order with a test. - Describe symbol and member classification in the api docs spec the way module items are indexed. - Rename the Go parser tests to say what they pin. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Tests selector2 / 100 PR test projects · 4 PR jobs, from 5 changed files. Selected PR test projects (2 / 100)
Selected PR jobs (4)
How these were chosen — grouped by what changed📦 affected project 🧪 🧪 🧪 Job reasons
Selection computed for commit |
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
|
✅ No documentation update needed. docs_required → already documented by name. Triggered signal:
|
Note
Depends on microsoft/aspire.dev#1917, which publishes the Go API reference this command reads. Not a merge blocker: this PR is safe to merge first, and until those pages are published the Go scope stays empty.
Description
Adds Go to
aspire docs api, solist,searchandgetaccept--language goand thegoscope once aspire.dev publishes the Go API reference under/reference/api/go/**.The Go reference deliberately mirrors the TypeScript route shape (module / item / member), so the CLI builds Go entries from sitemap path segments exactly the way it does for TypeScript. Page-body parsing is unchanged.
ApiReferenceLanguages.Go, agoroot scope and the/reference/api/gositemap route.BuildModuleItems). C# is untouched.IndexSchemaVersionfrom 1 to 2 so caches built by older CLIs rebuild (the schema version is part of the index fingerprint).docs/specs/api-docs-commands.mdanddocs/specs/cli-output-formats.md.This is safe to merge ahead of the docs. Until the site publishes
/reference/api/go/**, the Go scope is empty (No API entries found), and C# and TypeScript output is unchanged.This is the first step of the Go AppHost GA epic. The docs come first because the page shape drives what the parser has to understand.
Part of #21115
Validation
dotnet test --project tests/Aspire.Cli.Tests/Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.ApiDocsIndexServiceTests" --filter-class "*.ApiMemberMarkdownParserTests" --filter-class "*.ApiSitemapParserTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true": 44 passed, 0 failed.dotnet test --project tests/Aspire.Cli.Tests/Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.DocsCommandTests" --filter-class "*.ApiDocsFetcherTests" --filter-class "*.ApiDocsCacheTests" --filter-class "*.ApiDocsSourceConfigurationTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true": 27 passed, 0 failed.release/17.0site with the Go reference (docs__api__sitemapUrl=http://127.0.0.1:4399/sitemap-0.xml):docs api list goreturned 122 modules.docs api list go/aspire.hosting.redisreturned 17 entries andlist go/aspire.hosting.redis/redisresourcereturned 9 members.docs api search "redis password" --language gorankedgo/aspire.hosting.redis/redisresource/withpasswordfirst.docs api getreturned the served page content.docs api list csharp(186 entries) anddocs api list typescript(146 entries) are identical between the previously installed CLI (17.0.0-preview.1) and this build.Checklist
<remarks />and<code />elements on your triple slash comments?