Skip to content

Document Go support in aspire docs api - #1923

Merged
David Pine (IEvangelist) merged 1 commit into
release/17.0from
ievangelist-go-cli-docs
Oct 22, 2026
Merged

David Pine (IEvangelist) merged 1 commit into
release/17.0from
ievangelist-go-cli-docs

Conversation

@IEvangelist

@IEvangelist David Pine (IEvangelist) commented Oct 20, 2026 •

Copy link
Copy Markdown
Member

Important

Depends on:

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 Add Go API reference #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.

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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 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

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1923. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #1923 artifacts

This comment updates automatically when a new frontend build artifact is uploaded.

@IEvangelist
David Pine (IEvangelist) marked this pull request as draft October 20, 2026 13:29
@IEvangelist
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
@IEvangelist
David Pine (IEvangelist) merged commit 09d9aa3 into release/17.0 Oct 22, 2026
17 checks passed
@IEvangelist
David Pine (IEvangelist) deleted the ievangelist-go-cli-docs branch October 22, 2026 14:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants