Repository navigation
Document Go support in aspire docs api - #1923
Merged
Merged
Conversation
List `go` alongside `csharp` and `typescript` as an `aspire docs api` language in the command group overview, the `list` scope tables and examples, the `get` identifier examples, the `search --language` values, and the Aspire skills page. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
David Pine (IEvangelist)
requested a review
from Mitch Denny (mitchdenny)
as a code owner
October 20, 2026 05:10
Contributor
There was a problem hiding this comment.
🔵 Needs a closer look
Publication requires human confirmation that the dependent CLI support and Go reference routes will be available at the GA docs swap.
No open issues 🎉
What changed in this PR
Documents Go support in aspire docs api alongside C# and TypeScript for the planned Go AppHost GA release.
Changes:
- Adds Go language values, scopes, identifiers, and CLI examples.
- Updates the skills guide to include Go API documentation.
| File | Description |
|---|---|
| src/frontend/src/content/docs/reference/cli/commands/aspire-docs-api.mdx | Adds Go to supported API hierarchies. |
| src/frontend/src/content/docs/reference/cli/commands/aspire-docs-api-search.mdx | Documents the Go filter and search example. |
| src/frontend/src/content/docs/reference/cli/commands/aspire-docs-api-list.mdx | Adds Go scopes and listing examples. |
| src/frontend/src/content/docs/reference/cli/commands/aspire-docs-api-get.mdx | Adds a Go identifier and retrieval example. |
| src/frontend/src/content/docs/get-started/aspire-skills.mdx | Includes Go in API documentation guidance. |
Review effort: Balanced
Contributor
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
David Pine (IEvangelist)
marked this pull request as draft
October 20, 2026 13:29
Merged
David Pine (IEvangelist)
marked this pull request as ready for review
October 21, 2026 21:45
David Pine (IEvangelist)
added a commit
that referenced
this pull request
Oct 22, 2026
> [!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
This was referenced Oct 28, 2026
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.
Important
Depends on:
gotoaspire docs api, which these pages document.release/17.0only once that PR lands.Merge this PR after both.
Summary
Documents Go support in
aspire docs api. The CLI change addsgonext tocsharpandtypescript, 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,getandsearch:gois added to the language roots, the--languagevalues, the scope table (go,go/<module>andgo/<module>/<symbol>) and the identifier examples (for examplego/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.0yet, and the Go scope ofaspire docs apistays 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-aspireand the agent skill file) is about AppHost languages, not API docs.whats-new/aspire-17.mdxdoesn't mentionaspire docs apilanguages, so there's nothing to update there.Third-party links and affiliations
None.
Validation
.mdtwin (go/,aspire.hosting,aspire.hosting.redis,addredis,redisresource,redisresource/withpersistenceandaspire.hosting/withreference). All seven are also in that build'ssitemap-0.xml. Nonexistent routes return an error on the same server, so a 200 is meaningful.@mdx-js/mdx. A deliberately broken snippet is rejected, so the check can fail. Every code fence has a language id.git diff --check: both clean.Not run: the full
pnpm lint,pnpm test:unitand a site build. ESLint doesn't lint MDX and the repo has no Markdown linter.