From ea10e4e47605253784d506692a542db263ad7448 Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Fri, 2 Oct 2026 14:48:11 +0100 Subject: [PATCH 1/3] Split four sections of the doc-writer skill into reference files. --- .agents/skills/doc-writer/SKILL.md | 403 +----------------- .../references/common-documentation-issues.md | 70 +++ .../references/cross-referencing.md | 126 ++++++ .../references/integration-documentation.md | 199 +++++++++ .../references/testing-your-documentation.md | 126 ++++++ 5 files changed, 527 insertions(+), 397 deletions(-) create mode 100644 .agents/skills/doc-writer/references/common-documentation-issues.md create mode 100644 .agents/skills/doc-writer/references/cross-referencing.md create mode 100644 .agents/skills/doc-writer/references/integration-documentation.md create mode 100644 .agents/skills/doc-writer/references/testing-your-documentation.md diff --git a/.agents/skills/doc-writer/SKILL.md b/.agents/skills/doc-writer/SKILL.md index 9e07f32708..5d1d5cf110 100644 --- a/.agents/skills/doc-writer/SKILL.md +++ b/.agents/skills/doc-writer/SKILL.md @@ -7,8 +7,14 @@ description: Guidelines for producing accurate and maintainable documentation fo This skill provides guidelines for AI coding agents to help maintainers produce accurate and easy-to-maintain documentation for the Aspire project. The aspire.dev repository is the official documentation site for Aspire, and this skill helps ensure consistent, high-quality documentation. +When drafting or editing any document, follow the rules in the [Common Documentation Issues reference](./references/common-documentation-issues.md) + +When drafting or editing documentation for an Aspire integration, use the files locations and documentation structures in the [Integration Documentation reference](./references/integration-documentation.md). + Before finishing any draft, check it against the [Prose Patterns skill reference](./references/prose-patterns.md). +Before finishing any draft, test it as described in the [Testing Your Documentation reference](./references/testing-your-documentation.md). + ## Documentation Overview ### Site Structure @@ -543,205 +549,6 @@ Do **not** wrap a single language in a single-language `` component — th Use this exception at the operation level, not as a shortcut for the whole page. If some APIs are exported to TypeScript and others are not, provide synchronized C# and TypeScript tabs for every supported operation and place the limitation beside only the unsupported operation. -## Integration Documentation - -### File Location - -Place integration docs in the appropriate category folder under `src/frontend/src/content/docs/integrations/`: - -| Category | Folder | Examples | -| --------------- | ------------------ | ------------------------------- | -| AI/ML | `ai/` | Ollama, Azure OpenAI | -| Caching | `caching/` | Redis, Garnet, Valkey | -| Cloud | `cloud/` | Azure, AWS services | -| Compute | `compute/` | Docker, Kubernetes | -| Databases | `databases/` | PostgreSQL, SQL Server, MongoDB | -| Frameworks | `frameworks/` | Python, Rust, Orleans | -| Messaging | `messaging/` | RabbitMQ, Kafka | -| Observability | `observability/` | OpenTelemetry, Prometheus | -| Reverse Proxies | `reverse-proxies/` | YARP | -| Security | `security/` | Keycloak | - -### Integration Documentation Structure - -#### For Hosting-Only Integrations - -````mdx ---- -title: [Technology] integration -description: Learn how to use the [Technology] integration with Aspire. ---- - -import { Aside, Tabs, TabItem } from "@astrojs/starlight/components"; -import InstallPackage from "@components/InstallPackage.astro"; -import { Image } from "astro:assets"; - -import techIcon from "@assets/icons/technology.svg"; - -Technology logo - -Brief description of the technology and what the integration enables. - -## Hosting integration - - - -### Add [Technology] resource - - - - -```typescript title="apphost.mts" -import { createBuilder } from "./.aspire/modules/aspire.mjs"; - -const builder = await createBuilder(); - -const tech = await builder.addTechnology("tech"); - -await builder.build().run(); -``` - - - - -```csharp title="AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var tech = builder.AddTechnology("tech"); - -// After adding all resources, run the app... -builder.Build().Run(); -``` - - - - -### Configuration options - -Describe available configuration methods and options. - -## See also - -- [Official Technology documentation](https://...) -- [Related Aspire documentation](/path/to/related/) -```` - -#### For Hosting + Client Integrations - -Include both hosting and client sections: - -````mdx -## Hosting integration - - - -### Add [Technology] resource - - - - -```typescript title="apphost.mts" -import { createBuilder } from "./.aspire/modules/aspire.mjs"; - -const builder = await createBuilder(); - -const tech = await builder.addTechnology("tech"); - -const api = await builder.addProject("api", "../Api/Api.csproj"); -await api.withReference(tech); - -await builder.build().run(); -``` - - - - -```csharp title="AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var tech = builder.AddTechnology("tech"); - -builder.AddProject("api") - .WithReference(tech); - -builder.Build().Run(); -``` - - - - -### Hosting integration health checks - -[Health check information if applicable...] - -## Client integration - - - -### Add [Technology] client - -```csharp title="C# — Program.cs" -builder.AddTechnologyClient("tech"); -``` - -### Add keyed [Technology] client - -```csharp title="C# — Program.cs" -builder.AddKeyedTechnologyClient("tech"); -``` - -For more information, see [.NET dependency injection: Keyed services](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). - -### Configuration - -#### Connection strings - -The connection name must match the resource name defined in the AppHost. - -#### Configuration providers - -```json title="JSON — appsettings.json" -{ - "Aspire": { - "Technology": { - "myconnection": { - "Option1": "value" - } - } - } -} -``` - -### Client integration health checks - -[Health check information...] - -### Observability and telemetry - -[Logging and tracing information...] - -## See also - -- [Official documentation](https://...) -```` - -### Community Toolkit Integrations - -For integrations from the [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire), add the badge at the top: - -```mdx -import Badge from "@astrojs/starlight/components/Badge.astro"; - - -``` ## Updating Navigation @@ -868,133 +675,6 @@ Use `ThemeImage` whenever separate light and dark logo assets exist. For details on terminal recordings, including how to create and embed them, see the [terminal-recordings skill reference](./references/terminal-recordings.md). -## Testing Your Documentation - -Before submitting documentation: - -1. **Preview locally**: Run the site locally to verify rendering and content flow -2. **Check links**: Ensure all internal and external links work -3. **Validate code**: Test all code examples compile and run using `aspire run` -4. **Review formatting**: Verify components render correctly -5. **Run relevant tests**: Do not consider documentation or component work done until the affected tests pass -6. **Check navigation**: Confirm sidebar entries are correct -7. **Check integration logos**: At desktop and mobile widths, verify the full logo is visible, uncropped, and legible in both light and dark themes - -### Documentation Validation Strategy - -Use the smallest set of checks that proves the change is correct: - -- For MDX copy, structure, and navigation changes, verify the page locally and check the edited links. -- For custom component usage changes, run the component render tests that cover the affected behavior. -- For component prop surface changes, update and run the prop-contract coverage so editor completions and consumer typings stay intact. -- For interactive behavior changes, run targeted Playwright coverage for the scenario you changed rather than relying on unrelated broad suites. -- For browser-based local verification, use `playwright-cli` (`playwright-cli open `, `playwright-cli snapshot`, `playwright-cli click `) instead of Playwright MCP tools. -- For accessibility-sensitive changes, validate both the rendered page and any focused accessibility tests that exercise the affected interaction. - -### Custom Component and Test Expectations - -If a documentation change adds, removes, or materially changes a custom component, you should usually update one or more of these test layers: - -- `src/frontend/tests/unit/custom-components.vitest.test.ts` for runtime render coverage of custom Astro components. -- `src/frontend/tests/typecheck/component-props.contracts.ts` when component props change and the public prop contract should remain typed for MDX and other consumers. -- `src/frontend/tests/e2e/*.spec.ts` for user-visible interactions that depend on hydration, persistence, navigation, or accessibility behavior. - -Examples of scenarios that often merit targeted tests: - -- query-string or local-storage persistence -- cookie-consent or preference-driven behavior -- responsive behavior that changes across desktop, tablet, and mobile -- keyboard navigation, focus management, or screen-reader labeling -- repeated code examples that need distinct accessible labels or titles -- RSS, analytics, or other generated/static asset behaviors exposed through docs pages - -### Recommended Frontend Test Commands - -Prefer targeted validation over the slowest possible full-site build when the change does not require it. - -```bash -pnpm --dir ./src/frontend run test:unit:components -pnpm --dir ./src/frontend run test:unit:contracts -pnpm --dir ./src/frontend exec playwright test tests/e2e/.ts -``` - -If you changed custom components, docs interactions, or accessibility behavior, make sure the relevant targeted tests pass before submitting the work. - -### Installing the Aspire CLI - -Ensure you have the appropriate version of the Aspire CLI installed for testing. The version depends on what you're documenting: - -#### GA/Stable Builds (Default) - -For documenting released features: - -```bash -# Linux/macOS -curl -sSL https://aspire.dev/install.sh | bash - -# Windows (PowerShell) -irm https://aspire.dev/install.ps1 | iex -``` - -For complete installation instructions, see [Install Aspire CLI](https://aspire.dev/get-started/install-cli/). - -#### Nightly/Dev Builds - -For documenting features on the main branch that haven't been released yet: - -```bash -# Linux/macOS -curl -sSL https://aspire.dev/install.sh | bash -s -- --quality dev - -# Windows (PowerShell) -iex "& { $(irm https://aspire.dev/install.ps1) } -Quality 'dev'" -``` - -You can also access this via the download icon on aspire.dev and selecting "Dev" from the Channel selector. - -#### PR Builds - -For documenting features in specific pull requests before they merge: - -1. Go to the PR in [microsoft/aspire](https://github.com/microsoft/aspire) -2. Find the build artifacts in the Checks/Actions section -3. Download and install the CLI from the PR artifacts - -This is useful for getting an early start on documentation for upcoming features. - -#### Staging Builds - -For prerelease builds from the current release branch: - -```bash -# Linux/macOS -curl -sSL https://aspire.dev/install.sh | bash -s -- --quality staging - -# Windows (PowerShell) -iex "& { $(irm https://aspire.dev/install.ps1) } -Quality 'staging'" -``` - -### Running Locally - -The documentation site can be run locally using the Aspire CLI: - -```bash -aspire run -``` - - - -Use the Aspire CLI output or dashboard resource list to find the `frontend` endpoint, then open it with `playwright-cli`: - -```bash -playwright-cli open -playwright-cli snapshot -``` - -Use snapshot refs with `playwright-cli click ` for page interactions. - ## Cross-Referencing ### Link to Related Documentation @@ -1141,74 +821,3 @@ architecture-beta ```` Use the `architecture-beta` diagram type for service architecture diagrams. - -## Common Documentation Issues (From PR Feedback) - -The following rules are derived from common feedback patterns in documentation PRs. Following these rules will help avoid common mistakes. - -### General Writing Rules - -1. **Remove unnecessary commas**: Don't write "Now, that you have..." - write "Now that you have..." -2. **Avoid casual language**: Don't include phrases like "treat yourself to a coffee" or other informal asides in documentation -3. **Remove unused imports**: Don't import components that aren't used in the document -4. **Verify all internal links**: Links must point to pages that actually exist. Common mistakes: - - Linking to `/get-started/setup-and-tooling/` instead of `/get-started/prerequisites/` - - Linking to `/reference/cli/` for CLI installation instead of `/get-started/install-cli/` -5. **Add redirects when restructuring**: When moving or renaming documentation pages, add redirect entries in `src/frontend/config/redirects.mjs` - -### Code Example Rules - -1. **Use standard indentation**: For fluent APIs on newlines, use standard 4-space indentation, NOT alignment with the method call above - - ✅ Correct: - - ```csharp - builder.AddProject("api") - .WithReference(redis) - .WithExternalHttpEndpoints(); - ``` - - ❌ Incorrect (aligned indentation): - - ```csharp - builder.AddProject("api") - .WithReference(redis) - .WithExternalHttpEndpoints(); - ``` - -2. **Code block language identifiers**: Use only one language identifier, not duplicates like `csharp csharp` - -3. **Verify code syntax**: Check for typos in code: - - `main:app` not `main.app` (Python uvicorn module:app format) - - Verify package/module names are correct - -4. **Accurate technical descriptions**: - - `process.env` is an **object**, not a method - - `express` is NOT used to access environment variables (that's `process.env`) - - Don't claim libraries do things they don't do - -5. **Connection string environment variables**: - - For C#/.NET: Use `ConnectionStrings:resourcename` (colon separator) - - For Python/JavaScript: Use `ConnectionStrings__resourcename` (double underscore separator) - - Use the standard `ConnectionStrings__` pattern, not custom variable names like `ELASTICSEARCH_ENDPOINT` - -6. **Don't document deprecated APIs as primary examples**: If an API is deprecated, don't use it as the first or main example. Use current, recommended APIs. - -7. **Avoid insecure defaults in examples**: Don't include `TrustServerCertificate=true` in connection strings without noting it's for development only - -### Component Usage Rules - -1. **Match Pivot components to their PivotSelector**: When using nested Pivot components, ensure they reference the correct parent PivotSelector with the `key` attribute - -2. **Keep LinkCard descriptions concise**: Card descriptions should be short enough to not squeeze the UI. Prefer "Configure persistence..." over "Discover how to configure persistence..." - -3. **Avoid redundant Asides**: Don't have two Asides saying similar things near each other - -### Cross-Language Documentation - -When documenting integrations that support multiple languages (C#, Python, JavaScript): - -1. **Show complete, working examples** for each language -2. **Ensure variable names are defined** before they're used in code examples -3. **Verify the same resource name** is used consistently across language examples -4. **Don't remove code that defines variables** that are used later in the document diff --git a/.agents/skills/doc-writer/references/common-documentation-issues.md b/.agents/skills/doc-writer/references/common-documentation-issues.md new file mode 100644 index 0000000000..64901034a7 --- /dev/null +++ b/.agents/skills/doc-writer/references/common-documentation-issues.md @@ -0,0 +1,70 @@ +# Common Documentation Issues (From PR Feedback) + +The following rules are derived from common feedback patterns in documentation PRs. Following these rules will help avoid common mistakes. + +## General Writing Rules + +1. **Remove unnecessary commas**: Don't write "Now, that you have..." - write "Now that you have..." +2. **Avoid casual language**: Don't include phrases like "treat yourself to a coffee" or other informal asides in documentation +3. **Remove unused imports**: Don't import components that aren't used in the document +4. **Verify all internal links**: Links must point to pages that actually exist. Common mistakes: + - Linking to `/get-started/setup-and-tooling/` instead of `/get-started/prerequisites/` + - Linking to `/reference/cli/` for CLI installation instead of `/get-started/install-cli/` +5. **Add redirects when restructuring**: When moving or renaming documentation pages, add redirect entries in `src/frontend/config/redirects.mjs` + +## Code Example Rules + +1. **Use standard indentation**: For fluent APIs on newlines, use standard 4-space indentation, NOT alignment with the method call above + + ✅ Correct: + + ```csharp + builder.AddProject("api") + .WithReference(redis) + .WithExternalHttpEndpoints(); + ``` + + ❌ Incorrect (aligned indentation): + + ```csharp + builder.AddProject("api") + .WithReference(redis) + .WithExternalHttpEndpoints(); + ``` + +2. **Code block language identifiers**: Use only one language identifier, not duplicates like `csharp csharp` + +3. **Verify code syntax**: Check for typos in code: + - `main:app` not `main.app` (Python uvicorn module:app format) + - Verify package/module names are correct + +4. **Accurate technical descriptions**: + - `process.env` is an **object**, not a method + - `express` is NOT used to access environment variables (that's `process.env`) + - Don't claim libraries do things they don't do + +5. **Connection string environment variables**: + - For C#/.NET: Use `ConnectionStrings:resourcename` (colon separator) + - For Python/JavaScript: Use `ConnectionStrings__resourcename` (double underscore separator) + - Use the standard `ConnectionStrings__` pattern, not custom variable names like `ELASTICSEARCH_ENDPOINT` + +6. **Don't document deprecated APIs as primary examples**: If an API is deprecated, don't use it as the first or main example. Use current, recommended APIs. + +7. **Avoid insecure defaults in examples**: Don't include `TrustServerCertificate=true` in connection strings without noting it's for development only + +## Component Usage Rules + +1. **Match Pivot components to their PivotSelector**: When using nested Pivot components, ensure they reference the correct parent PivotSelector with the `key` attribute + +2. **Keep LinkCard descriptions concise**: Card descriptions should be short enough to not squeeze the UI. Prefer "Configure persistence..." over "Discover how to configure persistence..." + +3. **Avoid redundant Asides**: Don't have two Asides saying similar things near each other + +## Cross-Language Documentation + +When documenting integrations that support multiple languages (C#, Python, JavaScript): + +1. **Show complete, working examples** for each language +2. **Ensure variable names are defined** before they're used in code examples +3. **Verify the same resource name** is used consistently across language examples +4. **Don't remove code that defines variables** that are used later in the document diff --git a/.agents/skills/doc-writer/references/cross-referencing.md b/.agents/skills/doc-writer/references/cross-referencing.md new file mode 100644 index 0000000000..62b080cc89 --- /dev/null +++ b/.agents/skills/doc-writer/references/cross-referencing.md @@ -0,0 +1,126 @@ +# Testing Your Documentation + +Before submitting documentation: + +1. **Preview locally**: Run the site locally to verify rendering and content flow +2. **Check links**: Ensure all internal and external links work +3. **Validate code**: Test all code examples compile and run using `aspire run` +4. **Review formatting**: Verify components render correctly +5. **Run relevant tests**: Do not consider documentation or component work done until the affected tests pass +6. **Check navigation**: Confirm sidebar entries are correct +7. **Check integration logos**: At desktop and mobile widths, verify the full logo is visible, uncropped, and legible in both light and dark themes + +## Documentation Validation Strategy + +Use the smallest set of checks that proves the change is correct: + +- For MDX copy, structure, and navigation changes, verify the page locally and check the edited links. +- For custom component usage changes, run the component render tests that cover the affected behavior. +- For component prop surface changes, update and run the prop-contract coverage so editor completions and consumer typings stay intact. +- For interactive behavior changes, run targeted Playwright coverage for the scenario you changed rather than relying on unrelated broad suites. +- For browser-based local verification, use `playwright-cli` (`playwright-cli open `, `playwright-cli snapshot`, `playwright-cli click `) instead of Playwright MCP tools. +- For accessibility-sensitive changes, validate both the rendered page and any focused accessibility tests that exercise the affected interaction. + +## Custom Component and Test Expectations + +If a documentation change adds, removes, or materially changes a custom component, you should usually update one or more of these test layers: + +- `src/frontend/tests/unit/custom-components.vitest.test.ts` for runtime render coverage of custom Astro components. +- `src/frontend/tests/typecheck/component-props.contracts.ts` when component props change and the public prop contract should remain typed for MDX and other consumers. +- `src/frontend/tests/e2e/*.spec.ts` for user-visible interactions that depend on hydration, persistence, navigation, or accessibility behavior. + +Examples of scenarios that often merit targeted tests: + +- query-string or local-storage persistence +- cookie-consent or preference-driven behavior +- responsive behavior that changes across desktop, tablet, and mobile +- keyboard navigation, focus management, or screen-reader labeling +- repeated code examples that need distinct accessible labels or titles +- RSS, analytics, or other generated/static asset behaviors exposed through docs pages + +## Recommended Frontend Test Commands + +Prefer targeted validation over the slowest possible full-site build when the change does not require it. + +```bash +pnpm --dir ./src/frontend run test:unit:components +pnpm --dir ./src/frontend run test:unit:contracts +pnpm --dir ./src/frontend exec playwright test tests/e2e/.ts +``` + +If you changed custom components, docs interactions, or accessibility behavior, make sure the relevant targeted tests pass before submitting the work. + +## Installing the Aspire CLI + +Ensure you have the appropriate version of the Aspire CLI installed for testing. The version depends on what you're documenting: + +### GA/Stable Builds (Default) + +For documenting released features: + +```bash +# Linux/macOS +curl -sSL https://aspire.dev/install.sh | bash + +# Windows (PowerShell) +irm https://aspire.dev/install.ps1 | iex +``` + +For complete installation instructions, see [Install Aspire CLI](https://aspire.dev/get-started/install-cli/). + +### Nightly/Dev Builds + +For documenting features on the main branch that haven't been released yet: + +```bash +# Linux/macOS +curl -sSL https://aspire.dev/install.sh | bash -s -- --quality dev + +# Windows (PowerShell) +iex "& { $(irm https://aspire.dev/install.ps1) } -Quality 'dev'" +``` + +You can also access this via the download icon on aspire.dev and selecting "Dev" from the Channel selector. + +### PR Builds + +For documenting features in specific pull requests before they merge: + +1. Go to the PR in [microsoft/aspire](https://github.com/microsoft/aspire) +2. Find the build artifacts in the Checks/Actions section +3. Download and install the CLI from the PR artifacts + +This is useful for getting an early start on documentation for upcoming features. + +### Staging Builds + +For prerelease builds from the current release branch: + +```bash +# Linux/macOS +curl -sSL https://aspire.dev/install.sh | bash -s -- --quality staging + +# Windows (PowerShell) +iex "& { $(irm https://aspire.dev/install.ps1) } -Quality 'staging'" +``` + +## Running Locally + +The documentation site can be run locally using the Aspire CLI: + +```bash +aspire run +``` + + + +Use the Aspire CLI output or dashboard resource list to find the `frontend` endpoint, then open it with `playwright-cli`: + +```bash +playwright-cli open +playwright-cli snapshot +``` + +Use snapshot refs with `playwright-cli click ` for page interactions. diff --git a/.agents/skills/doc-writer/references/integration-documentation.md b/.agents/skills/doc-writer/references/integration-documentation.md new file mode 100644 index 0000000000..f8b9be0e52 --- /dev/null +++ b/.agents/skills/doc-writer/references/integration-documentation.md @@ -0,0 +1,199 @@ +# Integration Documentation + +## File Location + +Place integration docs in the appropriate category folder under `src/frontend/src/content/docs/integrations/`: + +| Category | Folder | Examples | +| --------------- | ------------------ | ------------------------------- | +| AI/ML | `ai/` | Ollama, Azure OpenAI | +| Caching | `caching/` | Redis, Garnet, Valkey | +| Cloud | `cloud/` | Azure, AWS services | +| Compute | `compute/` | Docker, Kubernetes | +| Databases | `databases/` | PostgreSQL, SQL Server, MongoDB | +| Frameworks | `frameworks/` | Python, Rust, Orleans | +| Messaging | `messaging/` | RabbitMQ, Kafka | +| Observability | `observability/` | OpenTelemetry, Prometheus | +| Reverse Proxies | `reverse-proxies/` | YARP | +| Security | `security/` | Keycloak | + +## Integration Documentation Structure + +### For Hosting-Only Integrations + +````mdx +--- +title: [Technology] integration +description: Learn how to use the [Technology] integration with Aspire. +--- + +import { Aside, Tabs, TabItem } from "@astrojs/starlight/components"; +import InstallPackage from "@components/InstallPackage.astro"; +import { Image } from "astro:assets"; + +import techIcon from "@assets/icons/technology.svg"; + +Technology logo + +Brief description of the technology and what the integration enables. + +## Hosting integration + + + +### Add [Technology] resource + + + + +```typescript title="apphost.mts" +import { createBuilder } from "./.aspire/modules/aspire.mjs"; + +const builder = await createBuilder(); + +const tech = await builder.addTechnology("tech"); + +await builder.build().run(); +``` + + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var tech = builder.AddTechnology("tech"); + +// After adding all resources, run the app... +builder.Build().Run(); +``` + + + + +### Configuration options + +Describe available configuration methods and options. + +## See also + +- [Official Technology documentation](https://...) +- [Related Aspire documentation](/path/to/related/) +```` + +### For Hosting + Client Integrations + +Include both hosting and client sections: + +````mdx +## Hosting integration + + + +### Add [Technology] resource + + + + +```typescript title="apphost.mts" +import { createBuilder } from "./.aspire/modules/aspire.mjs"; + +const builder = await createBuilder(); + +const tech = await builder.addTechnology("tech"); + +const api = await builder.addProject("api", "../Api/Api.csproj"); +await api.withReference(tech); + +await builder.build().run(); +``` + + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var tech = builder.AddTechnology("tech"); + +builder.AddProject("api") + .WithReference(tech); + +builder.Build().Run(); +``` + + + + +### Hosting integration health checks + +[Health check information if applicable...] + +## Client integration + + + +### Add [Technology] client + +```csharp title="C# — Program.cs" +builder.AddTechnologyClient("tech"); +``` + +### Add keyed [Technology] client + +```csharp title="C# — Program.cs" +builder.AddKeyedTechnologyClient("tech"); +``` + +For more information, see [.NET dependency injection: Keyed services](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). + +### Configuration + +#### Connection strings + +The connection name must match the resource name defined in the AppHost. + +#### Configuration providers + +```json title="JSON — appsettings.json" +{ + "Aspire": { + "Technology": { + "myconnection": { + "Option1": "value" + } + } + } +} +``` + +### Client integration health checks + +[Health check information...] + +### Observability and telemetry + +[Logging and tracing information...] + +## See also + +- [Official documentation](https://...) +```` + +## Community Toolkit Integrations + +For integrations from the [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire), add the badge at the top: + +```mdx +import Badge from "@astrojs/starlight/components/Badge.astro"; + + +``` diff --git a/.agents/skills/doc-writer/references/testing-your-documentation.md b/.agents/skills/doc-writer/references/testing-your-documentation.md new file mode 100644 index 0000000000..62b080cc89 --- /dev/null +++ b/.agents/skills/doc-writer/references/testing-your-documentation.md @@ -0,0 +1,126 @@ +# Testing Your Documentation + +Before submitting documentation: + +1. **Preview locally**: Run the site locally to verify rendering and content flow +2. **Check links**: Ensure all internal and external links work +3. **Validate code**: Test all code examples compile and run using `aspire run` +4. **Review formatting**: Verify components render correctly +5. **Run relevant tests**: Do not consider documentation or component work done until the affected tests pass +6. **Check navigation**: Confirm sidebar entries are correct +7. **Check integration logos**: At desktop and mobile widths, verify the full logo is visible, uncropped, and legible in both light and dark themes + +## Documentation Validation Strategy + +Use the smallest set of checks that proves the change is correct: + +- For MDX copy, structure, and navigation changes, verify the page locally and check the edited links. +- For custom component usage changes, run the component render tests that cover the affected behavior. +- For component prop surface changes, update and run the prop-contract coverage so editor completions and consumer typings stay intact. +- For interactive behavior changes, run targeted Playwright coverage for the scenario you changed rather than relying on unrelated broad suites. +- For browser-based local verification, use `playwright-cli` (`playwright-cli open `, `playwright-cli snapshot`, `playwright-cli click `) instead of Playwright MCP tools. +- For accessibility-sensitive changes, validate both the rendered page and any focused accessibility tests that exercise the affected interaction. + +## Custom Component and Test Expectations + +If a documentation change adds, removes, or materially changes a custom component, you should usually update one or more of these test layers: + +- `src/frontend/tests/unit/custom-components.vitest.test.ts` for runtime render coverage of custom Astro components. +- `src/frontend/tests/typecheck/component-props.contracts.ts` when component props change and the public prop contract should remain typed for MDX and other consumers. +- `src/frontend/tests/e2e/*.spec.ts` for user-visible interactions that depend on hydration, persistence, navigation, or accessibility behavior. + +Examples of scenarios that often merit targeted tests: + +- query-string or local-storage persistence +- cookie-consent or preference-driven behavior +- responsive behavior that changes across desktop, tablet, and mobile +- keyboard navigation, focus management, or screen-reader labeling +- repeated code examples that need distinct accessible labels or titles +- RSS, analytics, or other generated/static asset behaviors exposed through docs pages + +## Recommended Frontend Test Commands + +Prefer targeted validation over the slowest possible full-site build when the change does not require it. + +```bash +pnpm --dir ./src/frontend run test:unit:components +pnpm --dir ./src/frontend run test:unit:contracts +pnpm --dir ./src/frontend exec playwright test tests/e2e/.ts +``` + +If you changed custom components, docs interactions, or accessibility behavior, make sure the relevant targeted tests pass before submitting the work. + +## Installing the Aspire CLI + +Ensure you have the appropriate version of the Aspire CLI installed for testing. The version depends on what you're documenting: + +### GA/Stable Builds (Default) + +For documenting released features: + +```bash +# Linux/macOS +curl -sSL https://aspire.dev/install.sh | bash + +# Windows (PowerShell) +irm https://aspire.dev/install.ps1 | iex +``` + +For complete installation instructions, see [Install Aspire CLI](https://aspire.dev/get-started/install-cli/). + +### Nightly/Dev Builds + +For documenting features on the main branch that haven't been released yet: + +```bash +# Linux/macOS +curl -sSL https://aspire.dev/install.sh | bash -s -- --quality dev + +# Windows (PowerShell) +iex "& { $(irm https://aspire.dev/install.ps1) } -Quality 'dev'" +``` + +You can also access this via the download icon on aspire.dev and selecting "Dev" from the Channel selector. + +### PR Builds + +For documenting features in specific pull requests before they merge: + +1. Go to the PR in [microsoft/aspire](https://github.com/microsoft/aspire) +2. Find the build artifacts in the Checks/Actions section +3. Download and install the CLI from the PR artifacts + +This is useful for getting an early start on documentation for upcoming features. + +### Staging Builds + +For prerelease builds from the current release branch: + +```bash +# Linux/macOS +curl -sSL https://aspire.dev/install.sh | bash -s -- --quality staging + +# Windows (PowerShell) +iex "& { $(irm https://aspire.dev/install.ps1) } -Quality 'staging'" +``` + +## Running Locally + +The documentation site can be run locally using the Aspire CLI: + +```bash +aspire run +``` + + + +Use the Aspire CLI output or dashboard resource list to find the `frontend` endpoint, then open it with `playwright-cli`: + +```bash +playwright-cli open +playwright-cli snapshot +``` + +Use snapshot refs with `playwright-cli click ` for page interactions. From b738d4cb30cc4976c5eabc8edffc7bdf3f8ed11e Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Fri, 2 Oct 2026 15:06:04 +0100 Subject: [PATCH 2/3] Fixed the cross referencing section and reference. --- .agents/skills/doc-writer/SKILL.md | 84 +--------- .../references/cross-referencing.md | 147 ++++++------------ 2 files changed, 53 insertions(+), 178 deletions(-) diff --git a/.agents/skills/doc-writer/SKILL.md b/.agents/skills/doc-writer/SKILL.md index 5d1d5cf110..2353eef651 100644 --- a/.agents/skills/doc-writer/SKILL.md +++ b/.agents/skills/doc-writer/SKILL.md @@ -7,7 +7,9 @@ description: Guidelines for producing accurate and maintainable documentation fo This skill provides guidelines for AI coding agents to help maintainers produce accurate and easy-to-maintain documentation for the Aspire project. The aspire.dev repository is the official documentation site for Aspire, and this skill helps ensure consistent, high-quality documentation. -When drafting or editing any document, follow the rules in the [Common Documentation Issues reference](./references/common-documentation-issues.md) +When drafting or editing any document, follow the rules in the [Common Documentation Issues reference](./references/common-documentation-issues.md). + +When linking or referring to any other resource, follow the rules in the [Cross Referencing reference](./references/cross-referencing.md). When drafting or editing documentation for an Aspire integration, use the files locations and documentation structures in the [Integration Documentation reference](./references/integration-documentation.md). @@ -675,86 +677,6 @@ Use `ThemeImage` whenever separate light and dark logo assets exist. For details on terminal recordings, including how to create and embed them, see the [terminal-recordings skill reference](./references/terminal-recordings.md). -## Cross-Referencing - -### Link to Related Documentation - -Use standard Markdown links with absolute paths from the docs root: - -```markdown -For more information, see [Service Defaults](/fundamentals/service-defaults/). -``` - -### Inline API references - -Use `ApiReference` selectively to connect an explanation to API reference documentation, not to turn every API mention into a link. - -- In ordinary prose, use `` only on the **first named mention of a given API in an article**, when naming that API helps explain the behavior or accompanying example. Do not introduce an API name just to add a reference link. -- After that first mention, do **not** repeat the component or API reference link in ordinary prose, including prose in callouts and later sections. Prefer descriptive prose such as "this method" or "the dependency configuration." If repeating the name is necessary for clarity, use unlinked inline code appropriate to the AppHost language being discussed. -- Apply the ordinary-prose limit **per API, per article**, not per section or language tab. A different API can have its own first reference. -- In **bulleted or numbered lists**, including language-specific API explanation lists, repeated `` components are allowed. Treat equivalent API entries consistently, regardless of earlier mentions, rather than mixing linked components and unlinked API names. -- An optional API reference link in **See also** is also allowed. -- Keep API names in code samples as code; do not add reference markup inside code fences. -- Match the reference to the API actually used in the example. A PostgreSQL example calling `withPostgresMcp()` / `WithPostgresMcp()` must be introduced with `Aspire.Hosting.PostgresBuilderExtensions.WithPostgresMcp`, not the generic `WithMcpServer` API. - -For example, introduce an API once: - -```mdx -import ApiReference from '@components/ApiReference.astro'; - -For PostgreSQL, use to expose MCP tools for a database. -``` - -Later in the same article's ordinary prose, refer to "the PostgreSQL MCP helper" rather than repeating the linked API name. In an API explanation list, repeat the component for consistent entries: - -```mdx -- exposes MCP tools for a database. -- connects resources. -``` - -#### Selecting an overload - -Author `name`, `package`, and `parameterTypes` as explicit static props. The authoring validator does not evaluate spread objects: it reports `unsupported-spread` when a spread could supply or override any of these props, including optional ones. Remove the spread, or explicitly set all three props after the last spread so their values are known. - -By default, `ApiReference` shows the method name **without `()`** and links to the method group. To discuss a specific overload, supply `parameterTypes` as a static array of its **complete declared C# parameter types**, in declaration order. Copy the types from the generated C# catalog, preserving namespaces, generic arguments, and nullability. Include the `this` receiver's type for an extension method, but not the `this` keyword. Use `[]` only for a declaration with no parameters. - -```mdx -', - 'string', - 'string?', - ]} -/> -``` - -This links to the exact C# overload and displays `WithEnvironment(string name, string? value)`. The extension receiver is used for selection but omitted from the visible call signature. In TypeScript mode, the component uses the generated TypeScript export's own name and parameters; several C# overloads may share one TypeScript dispatcher. Do not copy C# parameter types into a TypeScript signature or select overloads by ordinal position. A missing or ambiguous match is an authoring error, not permission to link to the first overload. Use `package` when the same API is declared in multiple packages. - -Linked references reuse the code-block headers' C# and TypeScript icons from `material-icon-theme`, centered inside the code background. Do not add a separate icon or empty parentheses manually. `()` is shown only when an explicitly selected API genuinely has no call parameters. - -The component derives its top-positioned tooltip from the resolved API's generated summary or description, including the selected overload when specified. Do not duplicate that description in an authored `title` prop. When no description exists, the tooltip identifies the API and language instead. Tooltip titles are capped at 160 characters, including an ASCII `...` suffix when shortened, preferably at a word boundary. This presentation limit also applies to diagnostic titles; full source descriptions, diagnostics, and visible API labels remain unchanged. - -Title-based tooltips use the shared `src/frontend/src/scripts/tooltips.ts` lifecycle on initial load and after ClientRouter navigation. Keep API descriptions text-only with `data-tippy-allowhtml="false"`; do not add a competing per-component initializer. -The lifecycle is installed once per document; HMR disposal removes its listeners, restores titles, and destroys tooltip instances before the replacement module initializes. - -### Reference NuGet Packages - -Use the 📦 emoji with links: - -```markdown -Install the [📦 Aspire.Hosting.Redis](https://nuget.org/packages/Aspire.Hosting.Redis) package. -``` - -### See Also Sections - -End pages with a "See also" section linking to: - -- Official technology documentation -- Related Aspire documentation -- NuGet package pages -- GitHub repositories (when applicable) - ## Localization The aspire.dev site supports multiple languages. When creating new content: diff --git a/.agents/skills/doc-writer/references/cross-referencing.md b/.agents/skills/doc-writer/references/cross-referencing.md index 62b080cc89..20966ba35e 100644 --- a/.agents/skills/doc-writer/references/cross-referencing.md +++ b/.agents/skills/doc-writer/references/cross-referencing.md @@ -1,126 +1,79 @@ -# Testing Your Documentation +# Cross-Referencing -Before submitting documentation: +## Link to Related Documentation -1. **Preview locally**: Run the site locally to verify rendering and content flow -2. **Check links**: Ensure all internal and external links work -3. **Validate code**: Test all code examples compile and run using `aspire run` -4. **Review formatting**: Verify components render correctly -5. **Run relevant tests**: Do not consider documentation or component work done until the affected tests pass -6. **Check navigation**: Confirm sidebar entries are correct -7. **Check integration logos**: At desktop and mobile widths, verify the full logo is visible, uncropped, and legible in both light and dark themes +Use standard Markdown links with absolute paths from the docs root: -## Documentation Validation Strategy - -Use the smallest set of checks that proves the change is correct: - -- For MDX copy, structure, and navigation changes, verify the page locally and check the edited links. -- For custom component usage changes, run the component render tests that cover the affected behavior. -- For component prop surface changes, update and run the prop-contract coverage so editor completions and consumer typings stay intact. -- For interactive behavior changes, run targeted Playwright coverage for the scenario you changed rather than relying on unrelated broad suites. -- For browser-based local verification, use `playwright-cli` (`playwright-cli open `, `playwright-cli snapshot`, `playwright-cli click `) instead of Playwright MCP tools. -- For accessibility-sensitive changes, validate both the rendered page and any focused accessibility tests that exercise the affected interaction. - -## Custom Component and Test Expectations - -If a documentation change adds, removes, or materially changes a custom component, you should usually update one or more of these test layers: - -- `src/frontend/tests/unit/custom-components.vitest.test.ts` for runtime render coverage of custom Astro components. -- `src/frontend/tests/typecheck/component-props.contracts.ts` when component props change and the public prop contract should remain typed for MDX and other consumers. -- `src/frontend/tests/e2e/*.spec.ts` for user-visible interactions that depend on hydration, persistence, navigation, or accessibility behavior. - -Examples of scenarios that often merit targeted tests: - -- query-string or local-storage persistence -- cookie-consent or preference-driven behavior -- responsive behavior that changes across desktop, tablet, and mobile -- keyboard navigation, focus management, or screen-reader labeling -- repeated code examples that need distinct accessible labels or titles -- RSS, analytics, or other generated/static asset behaviors exposed through docs pages - -## Recommended Frontend Test Commands - -Prefer targeted validation over the slowest possible full-site build when the change does not require it. - -```bash -pnpm --dir ./src/frontend run test:unit:components -pnpm --dir ./src/frontend run test:unit:contracts -pnpm --dir ./src/frontend exec playwright test tests/e2e/.ts +```markdown +For more information, see [Service Defaults](/fundamentals/service-defaults/). ``` -If you changed custom components, docs interactions, or accessibility behavior, make sure the relevant targeted tests pass before submitting the work. +## Inline API references -## Installing the Aspire CLI +Use `ApiReference` selectively to connect an explanation to API reference documentation, not to turn every API mention into a link. -Ensure you have the appropriate version of the Aspire CLI installed for testing. The version depends on what you're documenting: +- In ordinary prose, use `` only on the **first named mention of a given API in an article**, when naming that API helps explain the behavior or accompanying example. Do not introduce an API name just to add a reference link. +- After that first mention, do **not** repeat the component or API reference link in ordinary prose, including prose in callouts and later sections. Prefer descriptive prose such as "this method" or "the dependency configuration." If repeating the name is necessary for clarity, use unlinked inline code appropriate to the AppHost language being discussed. +- Apply the ordinary-prose limit **per API, per article**, not per section or language tab. A different API can have its own first reference. +- In **bulleted or numbered lists**, including language-specific API explanation lists, repeated `` components are allowed. Treat equivalent API entries consistently, regardless of earlier mentions, rather than mixing linked components and unlinked API names. +- An optional API reference link in **See also** is also allowed. +- Keep API names in code samples as code; do not add reference markup inside code fences. +- Match the reference to the API actually used in the example. A PostgreSQL example calling `withPostgresMcp()` / `WithPostgresMcp()` must be introduced with `Aspire.Hosting.PostgresBuilderExtensions.WithPostgresMcp`, not the generic `WithMcpServer` API. -### GA/Stable Builds (Default) +For example, introduce an API once: -For documenting released features: +```mdx +import ApiReference from '@components/ApiReference.astro'; -```bash -# Linux/macOS -curl -sSL https://aspire.dev/install.sh | bash - -# Windows (PowerShell) -irm https://aspire.dev/install.ps1 | iex +For PostgreSQL, use to expose MCP tools for a database. ``` -For complete installation instructions, see [Install Aspire CLI](https://aspire.dev/get-started/install-cli/). - -### Nightly/Dev Builds - -For documenting features on the main branch that haven't been released yet: +Later in the same article's ordinary prose, refer to "the PostgreSQL MCP helper" rather than repeating the linked API name. In an API explanation list, repeat the component for consistent entries: -```bash -# Linux/macOS -curl -sSL https://aspire.dev/install.sh | bash -s -- --quality dev - -# Windows (PowerShell) -iex "& { $(irm https://aspire.dev/install.ps1) } -Quality 'dev'" +```mdx +- exposes MCP tools for a database. +- connects resources. ``` -You can also access this via the download icon on aspire.dev and selecting "Dev" from the Channel selector. - -### PR Builds +### Selecting an overload -For documenting features in specific pull requests before they merge: +Author `name`, `package`, and `parameterTypes` as explicit static props. The authoring validator does not evaluate spread objects: it reports `unsupported-spread` when a spread could supply or override any of these props, including optional ones. Remove the spread, or explicitly set all three props after the last spread so their values are known. -1. Go to the PR in [microsoft/aspire](https://github.com/microsoft/aspire) -2. Find the build artifacts in the Checks/Actions section -3. Download and install the CLI from the PR artifacts +By default, `ApiReference` shows the method name **without `()`** and links to the method group. To discuss a specific overload, supply `parameterTypes` as a static array of its **complete declared C# parameter types**, in declaration order. Copy the types from the generated C# catalog, preserving namespaces, generic arguments, and nullability. Include the `this` receiver's type for an extension method, but not the `this` keyword. Use `[]` only for a declaration with no parameters. -This is useful for getting an early start on documentation for upcoming features. +```mdx +', + 'string', + 'string?', + ]} +/> +``` -### Staging Builds +This links to the exact C# overload and displays `WithEnvironment(string name, string? value)`. The extension receiver is used for selection but omitted from the visible call signature. In TypeScript mode, the component uses the generated TypeScript export's own name and parameters; several C# overloads may share one TypeScript dispatcher. Do not copy C# parameter types into a TypeScript signature or select overloads by ordinal position. A missing or ambiguous match is an authoring error, not permission to link to the first overload. Use `package` when the same API is declared in multiple packages. -For prerelease builds from the current release branch: +Linked references reuse the code-block headers' C# and TypeScript icons from `material-icon-theme`, centered inside the code background. Do not add a separate icon or empty parentheses manually. `()` is shown only when an explicitly selected API genuinely has no call parameters. -```bash -# Linux/macOS -curl -sSL https://aspire.dev/install.sh | bash -s -- --quality staging +The component derives its top-positioned tooltip from the resolved API's generated summary or description, including the selected overload when specified. Do not duplicate that description in an authored `title` prop. When no description exists, the tooltip identifies the API and language instead. Tooltip titles are capped at 160 characters, including an ASCII `...` suffix when shortened, preferably at a word boundary. This presentation limit also applies to diagnostic titles; full source descriptions, diagnostics, and visible API labels remain unchanged. -# Windows (PowerShell) -iex "& { $(irm https://aspire.dev/install.ps1) } -Quality 'staging'" -``` +Title-based tooltips use the shared `src/frontend/src/scripts/tooltips.ts` lifecycle on initial load and after ClientRouter navigation. Keep API descriptions text-only with `data-tippy-allowhtml="false"`; do not add a competing per-component initializer. +The lifecycle is installed once per document; HMR disposal removes its listeners, restores titles, and destroys tooltip instances before the replacement module initializes. -## Running Locally +## Reference NuGet Packages -The documentation site can be run locally using the Aspire CLI: +Use the 📦 emoji with links: -```bash -aspire run +```markdown +Install the [📦 Aspire.Hosting.Redis](https://nuget.org/packages/Aspire.Hosting.Redis) package. ``` - +## See Also Sections -Use the Aspire CLI output or dashboard resource list to find the `frontend` endpoint, then open it with `playwright-cli`: - -```bash -playwright-cli open -playwright-cli snapshot -``` +End pages with a "See also" section linking to: -Use snapshot refs with `playwright-cli click ` for page interactions. +- Official technology documentation +- Related Aspire documentation +- NuGet package pages +- GitHub repositories (when applicable) From 16d3b22c49dbf9da58380f7e5f5fe6c109a4c2d9 Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Fri, 2 Oct 2026 16:33:01 +0100 Subject: [PATCH 3/3] Integrated feedback from @Copilot. --- .agents/skills/doc-writer/SKILL.md | 4 ++-- .../doc-writer/references/testing-your-documentation.md | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.agents/skills/doc-writer/SKILL.md b/.agents/skills/doc-writer/SKILL.md index 2353eef651..65018f4c92 100644 --- a/.agents/skills/doc-writer/SKILL.md +++ b/.agents/skills/doc-writer/SKILL.md @@ -9,9 +9,9 @@ This skill provides guidelines for AI coding agents to help maintainers produce When drafting or editing any document, follow the rules in the [Common Documentation Issues reference](./references/common-documentation-issues.md). -When linking or referring to any other resource, follow the rules in the [Cross Referencing reference](./references/cross-referencing.md). +When linking or referring to any other resource, follow the rules in the [Cross-Referencing reference](./references/cross-referencing.md). -When drafting or editing documentation for an Aspire integration, use the files locations and documentation structures in the [Integration Documentation reference](./references/integration-documentation.md). +When drafting or editing documentation for an Aspire integration, use the file locations and documentation structures in the [Integration Documentation reference](./references/integration-documentation.md). Before finishing any draft, check it against the [Prose Patterns skill reference](./references/prose-patterns.md). diff --git a/.agents/skills/doc-writer/references/testing-your-documentation.md b/.agents/skills/doc-writer/references/testing-your-documentation.md index 62b080cc89..ba783b2cbb 100644 --- a/.agents/skills/doc-writer/references/testing-your-documentation.md +++ b/.agents/skills/doc-writer/references/testing-your-documentation.md @@ -36,6 +36,7 @@ Examples of scenarios that often merit targeted tests: - responsive behavior that changes across desktop, tablet, and mobile - keyboard navigation, focus management, or screen-reader labeling - repeated code examples that need distinct accessible labels or titles + - RSS, analytics, or other generated/static asset behaviors exposed through docs pages ## Recommended Frontend Test Commands @@ -45,7 +46,7 @@ Prefer targeted validation over the slowest possible full-site build when the ch ```bash pnpm --dir ./src/frontend run test:unit:components pnpm --dir ./src/frontend run test:unit:contracts -pnpm --dir ./src/frontend exec playwright test tests/e2e/.ts +pnpm --dir ./src/frontend exec playwright test tests/e2e/.spec.ts ``` If you changed custom components, docs interactions, or accessibility behavior, make sure the relevant targeted tests pass before submitting the work.