Add GitHub Pages documentation site with docfx by shenglol · Pull Request #350 · Azure/bicep-extensibility

shenglol · 2026-04-09T02:54:37Z

Summary

Sets up a docfx-powered documentation site deployed to GitHub Pages.

What's included

Documentation structure:

Home — platform overview with package table and quick links
Contract — V2 API contract, preview operation deep-dive, async operations guide
SDKs — Core (models, OneOf, validation) and AspNetCore (ExtensionApplication, behaviors, typed handlers)
Tutorials — Getting Started, Typed Handlers, Behaviors, Validators

Infrastructure:

docs/docfx.json — docfx configuration targeting Core and AspNetCore projects
.github/workflows/docs.yml — CI/CD: TypeSpec → OpenAPI → docfx → GitHub Pages
docs/api-explorer/index.html — standalone Scalar API explorer

Code change:

ExtensionApplication.Build() made public for 1P customers using Service Fabric (KestrelCommunicationListener)

Housekeeping:

Moved v1/ and v2/ under docs/contract/ (v1 excluded from site output)
Updated tspconfig.yaml and AspNetCore csproj for new openapi.yaml path
Added docs/_site/ and docs/api/ to .gitignore

Test locally

# 1. Install docfx (one-time)
dotnet tool install -g docfx

# 2. Build and serve the site
docfx docs/docfx.json --serve

Open http://localhost:8080 and verify:

Home — landing page with package table and quick links
Contract tab — contract.md, async-operations.md, preview-operation.md render correctly
SDKs tab — Core and AspNetCore pages with 1P audience note on AspNetCore, and generated API docs for both packages
Tutorials tab — Getting Started, Typed Handlers, Behaviors, Validators

To enable GitHub Pages

After merge, go to Settings → Pages → Source: GitHub Actions.

- docfx.json targeting Core and AspNetCore projects - filterConfig.yml to scope to Azure.Deployments.Extensibility namespaces - Top-level toc.yml and index.md landing page - .gitignore entries for docs/_site/ and docs/api/

- Move v1/ and v2/ directories under docs/contract/ - Remove duplicate markdown from contract/v2/ (keep only openapi.yaml) - Add contract section index and toc - Add Scalar API explorer standalone page - Update openapi.yaml references in tspconfig.yaml and AspNetCore csproj - Fix .tsp links in contract.md to point to GitHub source

- sdks/index.md with package overview and 1P audience note - sdks/core.md covering models, OneOf, errors, validation framework - sdks/aspnetcore.md covering ExtensionApplication, handler resolution, generic handlers, typed handler base classes, behavior pipeline, built-in behaviors, and Scalar API explorer

- getting-started.md with 1P audience note and generic handler mention - typed-handlers.md covering TypedResource*Handler base classes - behaviors.md covering pipeline decorators, scopes, and execution order - validators.md covering ModelValidator<T>, criteria, and error aggregation

- Triggers on push to main and manual dispatch - Generates OpenAPI spec from TypeSpec - Builds docfx site - Deploys to GitHub Pages via actions/deploy-pages@v4

Enables 1P customers hosting inside Service Fabric (KestrelCommunicationListener) to obtain the configured WebApplication without calling Run().

codecov · 2026-04-09T02:57:58Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 45.04%. Comparing base (a7c706e) to head (81b8c3f).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #350   +/-   ##
=======================================
  Coverage   45.04%   45.04%           
=======================================
  Files         108      108           
  Lines        2100     2100           
  Branches      235      235           
=======================================
  Hits          946      946           
  Misses       1111     1111           
  Partials       43       43

Files with missing lines	Coverage Δ
...s.Extensibility.AspNetCore/ExtensionApplication.cs	`0.00% <ø> (ø)`
...ore/Handlers/TypedResourceCreateOrUpdateHandler.cs	`0.00% <ø> (ø)`
....AspNetCore/Handlers/TypedResourceDeleteHandler.cs	`0.00% <ø> (ø)`
...AspNetCore/Handlers/TypedResourceGetHttpHandler.cs	`0.00% <ø> (ø)`
...AspNetCore/Handlers/TypedResourcePreviewHandler.cs	`0.00% <ø> (ø)`
...Extensibility.Core/V2/Contracts/Models/Resource.cs	`25.00% <ø> (ø)`
...bility.Core/V2/Contracts/Models/ResourcePreview.cs	`0.00% <ø> (ø)`
...2/Contracts/Models/ResourcePreviewSpecification.cs	`0.00% <ø> (ø)`
...lity.Core/V2/Contracts/Models/ResourceReference.cs	`36.84% <ø> (ø)`
....Core/V2/Contracts/Models/ResourceSpecification.cs	`36.84% <ø> (ø)`

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

This PR sets up a docfx-based documentation site (intended for GitHub Pages), adds SDK/tutorial documentation, relocates the generated OpenAPI output under docs/contract/v2, and exposes ExtensionApplication.Build() publicly for custom hosting scenarios.

Changes:

Make ExtensionApplication.Build() public and document intended hosting use-cases.
Move OpenAPI emitter output and embedded-resource path to docs/contract/v2/openapi.yaml.
Add docfx configuration, docs structure (contract/SDKs/tutorials), and a Pages deployment workflow.

Reviewed changes

Copilot reviewed 22 out of 28 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/Azure.Deployments.Extensibility.AspNetCore/ExtensionApplication.cs	Exposes `Build()` publicly with XML docs for custom lifecycle hosting.
src/Azure.Deployments.Extensibility.AspNetCore/Azure.Deployments.Extensibility.AspNetCore.csproj	Updates embedded OpenAPI resource path to `docs/contract/v2/openapi.yaml`.
spec/tspconfig.yaml	Changes TypeSpec OpenAPI emitter output directory to `../docs/contract/v2`.
docs/tutorials/validators.md	Adds validator tutorial content (includes a behavior detail that needs correction).
docs/tutorials/typed-handlers.md	Adds typed handlers tutorial content.
docs/tutorials/toc.yml	Adds tutorials TOC for docfx navigation.
docs/tutorials/getting-started.md	Adds getting started tutorial for AspNetCore SDK usage.
docs/tutorials/behaviors.md	Adds behaviors tutorial content and registration patterns.
docs/toc.yml	Adds top-level documentation navigation.
docs/sdks/toc.yml	Adds SDK section TOC.
docs/sdks/index.md	Adds SDK overview/entry page.
docs/sdks/core.md	Adds Core SDK conceptual documentation.
docs/sdks/aspnetcore.md	Adds AspNetCore SDK conceptual documentation.
docs/index.md	Adds docs landing page with quick links.
docs/filterConfig.yml	Adds docfx API filter configuration.
docs/docfx.json	Adds docfx build configuration for site generation.
docs/contract/v2/openapi.yaml	Adds generated OpenAPI spec (contains stale external doc links).
docs/contract/v1/extensibility-provider-contract.md	Adds legacy v1 contract summary page (minor grammar issue).
docs/contract/v1/extensibility-provider-api.json	Adds legacy v1 OpenAPI JSON.
docs/contract/toc.yml	Adds contract section TOC.
docs/contract/preview-operation.md	Adds detailed preview-operation documentation (contains TODO placeholders).
docs/contract/index.md	Adds contract section landing page.
docs/contract/contract.md	Updates contract doc links (core.tsp/http.tsp and OpenAPI path).
docs/contract/async-operations.md	Adds detailed async operations documentation.
docs/api-explorer/index.html	Adds Scalar standalone explorer page referencing `contract/v2/openapi.yaml`.
doc-update-plan.md	Removes outdated doc update plan document.
.gitignore	Ignores docfx output folders.
.github/workflows/docs.yml	Adds GitHub Pages docs build/deploy workflow.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/tutorials/validators.md

docs/tutorials/typed-handlers.md

- Fix validators.md: criteria short-circuit on failure (not evaluated further) - Fix typed-handlers.md: remove ambiguous ? from JsonObject comment

Remove redundant <typeparam> tags from 2-type-parameter derived classes. The <inheritdoc> directive already copies them from the base class.

Filter out legacy V1 types from Azure.Deployments.Extensibility.Core (IExtensibilityProvider, ModelMapper, validators, etc.) while keeping all V2 types under Core.V2 and the full AspNetCore surface.

Move the generated API reference from a standalone top-level tab into the SDKs section sidebar (Overview > Core > AspNetCore > API Reference). Reduces top nav to 4 tabs: Home, Contract, SDKs, Tutorials.

- Split API metadata into per-SDK outputs (api-core, api-aspnetcore) nested under sdks/ so DocFX can resolve breadcrumbs - Nest API Reference under Core and AspNetCore in sdks/toc.yml - Add _baseUrl to globalMetadata for sitemap generation - Pin @scalar/api-reference to v1.25.68 in api-explorer - Pin .NET SDK version in CI via global-json-file - Replace published TODO markers with [!NOTE] callouts - Add API Reference xref links to landing page quick links - Add explanatory comments to filterConfig.yml exclusions - Add 404.md for GitHub Pages - Update .gitignore for new api output directories

Add an API Explorer entry to the Contract section sidebar and update the OpenAPI Specification section in contract.md to link to the local API Explorer page instead of the external Scalar sandbox.

shenglol added 8 commits April 8, 2026 19:51

Add docfx configuration and site scaffolding

0ef18f0

- docfx.json targeting Core and AspNetCore projects - filterConfig.yml to scope to Azure.Deployments.Extensibility namespaces - Top-level toc.yml and index.md landing page - .gitignore entries for docs/_site/ and docs/api/

Add GitHub Pages deployment workflow

876cfb4

- Triggers on push to main and manual dispatch - Generates OpenAPI spec from TypeSpec - Builds docfx site - Deploys to GitHub Pages via actions/deploy-pages@v4

Make ExtensionApplication.Build() public

b9a484d

Enables 1P customers hosting inside Service Fabric (KestrelCommunicationListener) to obtain the configured WebApplication without calling Run().

Mark all phases complete in doc-update-plan.md

df9b158

Remove doc-update-plan.md (all phases complete)

7d76d41

Copilot AI review requested due to automatic review settings April 9, 2026 02:54

Copilot started reviewing on behalf of shenglol April 9, 2026 02:55 View session

shenglol changed the title ~~test~~ Add GitHub Pages documentation site with docfx Apr 9, 2026

Copilot AI reviewed Apr 9, 2026

View reviewed changes

docs/tutorials/validators.md Outdated Show resolved Hide resolved

docs/tutorials/typed-handlers.md Outdated Show resolved Hide resolved

Temporarily trigger docs workflow on feature branch

eb3c5be

shenglol had a problem deploying to github-pages April 9, 2026 03:01 — with GitHub Actions Failure

shenglol added 8 commits April 8, 2026 20:05

Remove temporary branch trigger from docs workflow

ca8d1de

Address PR review comments

21e52c0

- Fix validators.md: criteria short-circuit on failure (not evaluated further) - Fix typed-handlers.md: remove ambiguous ? from JsonObject comment

Fix duplicate typeparam warnings in XML doc comments

a3f09f6

Remove redundant <typeparam> tags from 2-type-parameter derived classes. The <inheritdoc> directive already copies them from the base class.

Exclude V1 types from docfx API reference

d45d517

Filter out legacy V1 types from Azure.Deployments.Extensibility.Core (IExtensibilityProvider, ModelMapper, validators, etc.) while keeping all V2 types under Core.V2 and the full AspNetCore surface.

Merge API Reference under SDKs tab

91b42ea

Move the generated API reference from a standalone top-level tab into the SDKs section sidebar (Overview > Core > AspNetCore > API Reference). Reduces top nav to 4 tabs: Home, Contract, SDKs, Tutorials.

Add API Explorer to Contract TOC and replace Scalar sandbox link

01e9079

Add an API Explorer entry to the Contract section sidebar and update the OpenAPI Specification section in contract.md to link to the local API Explorer page instead of the external Scalar sandbox.

Rename API Explorer to OpenAPI Explorer

81b8c3f

gary-x-li approved these changes Apr 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add GitHub Pages documentation site with docfx#350

Add GitHub Pages documentation site with docfx#350
shenglol wants to merge 17 commits intomainfrom
shenglol/doc-gh-page

shenglol commented Apr 9, 2026 •

edited

Loading

Uh oh!

codecov bot commented Apr 9, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

shenglol commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's included

Test locally

To enable GitHub Pages

Uh oh!

codecov bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

shenglol commented Apr 9, 2026 •

edited

Loading

codecov bot commented Apr 9, 2026 •

edited

Loading