Implement Bicep module documentation generation by jaredfholgate · Pull Request #20183 · Azure/bicep

Jared Holgate (jaredfholgate) · 2026-08-14T12:56:26Z

Description

Adds the experimental bicep docs generate command, which renders module documentation from Bicep's semantic model plus discovered usage examples through Scriban.

Implements REP 0025: Module documentation generation commands and supersedes Azure/bicep#19694.

The validated AVM templates, root configuration, semantic verifier, and full-repository runner are in Azure/azure-verified-modules-tools PR #67.

Example usage

# Generate README.md beside one module
bicep docs generate .\main.bicep

# Render one module to stdout
bicep docs generate .\main.bicep --stdout

# Generate documentation for matched modules
bicep docs generate --pattern '.\modules\**\main.bicep'

--stdout follows the existing Bicep output-option contract and cannot be combined with --pattern, --outdir, or --outfile.

What's included

CLI

one bicep docs generate command with explicit .bicep or --pattern input
standard --stdout, --outdir, and --outfile behavior
built-in Markdown, custom Scriban templates, includes, and ordered inline/JSON-file custom values
one SARIF document per invocation for bulk compilation, rendering, and write failures
shared compilation state across bulk generation

Core engine

reusable deterministic typed model and renderer in Bicep.Core
resource types, parameters, outputs, exported types, exported variables, exported functions, referenced modules, and usage examples
recursive type expansion with cycle detection, a node budget, truncation metadata, and cancellation
generic example sources and parent-to-child reassignment without AVM-specific hard-coding

Configuration

typed documentation section in bicepconfig.json
built-in defaults and merged bicepconfig.schema.json validation/IntelliSense
config-relative template paths anchored to the resolved config file
per-source standard nearest-file configuration resolution

JSON-RPC

bicep/generateDocs and bicep/outputDocs remain directly on IBicepClient
each path uses its own resolved bicepconfig.json
shared compilation state for bulk requests
request cancellation reaches model construction and rendering

Configuration

{
  "documentation": {
    "output": {
      "file": "README.md"
    },
    "template": {
      "file": "docs/templates/readme.scriban",
      "includeRoot": "docs/templates",
      "values": {
        "owner": "Platform Team"
      }
    },
    "examples": {
      "sources": [
        {
          "path": "examples",
          "include": ["*.bicep", "**/main.bicep"],
          "exclude": ["**/dependencies*.bicep"]
        }
      ],
      "reassignments": []
    }
  }
}

Configured relative template paths are anchored to the resolved config file's directory. CLI template paths remain current-directory-relative.

bicepconfig.json remains nearest-file-wins with no ancestor merging. A module with its own config does not inherit repository-level documentation settings and receives built-in defaults for omitted values. Repositories requiring uniform settings should prevent nested configs until configuration inheritance is designed separately.

Full experimental reference: docs/experimental/docs-commands.md.

Impact on existing commands

InputOutputArgumentsResolver supports a fixed output filename resolver so docs can use README.md rather than extension replacement. Existing callers omit it and retain their existing behavior. Common filesystem/path exception predicates now live in Bicep.IO; CLI-wide central exception handling is intentionally not changed in this PR.

Documentation uses the standard non-atomic OutputWriter.WriteToFileAsync path used by other commands. Compilation and rendering complete before the write, so those failures do not overwrite an existing output.

Validation

Bicep.Core.UnitTests: 7,001 passed
Bicep.Cli.IntegrationTests: 1,137 passed
Bicep.Cli.UnitTests: 72 passed
Bicep.IO.UnitTests: 145 passed
Bicep.RpcClient.Tests: 96 passed, 1 skipped
Bicep solution build: 0 warnings, 0 errors
VS Code UI and extension builds passed
all newly introduced and directly modified documentation/configuration production paths reached 100% executable line and branch coverage

Trimmed single-file publish — Release win-x64, commit 583ede7ae0617361fa66e08feae8d5d457de3017:

built-in stdout output matched the comprehensive golden exactly
custom Scriban rendering with include matched exactly
config-relative template/include resolution from bicepconfig.json matched exactly
executable SHA256: 30F50C158D1C6715E1A28C1FDF8F9691EE243226FE24AC82970AADD610BCCB18

Full Azure/bicep-registry-modules validation against the same Bicep commit:

573 modules compared in 00:13:36.2321022
572 READMEs generated and all 572 matched byte-for-byte
one module was not written because avm/ptn/app/container-job-toolkit has genuine compilation errors (BCP426, BCP104, BCP287, and BCP036)
example-model mismatches: 0
parameter-model differences: 9 modules exposing additional typed paths unavailable to the legacy ARM-JSON generator; no expected paths are missing
full evidence: https://gist.github.com/jaredfholgate/71babd2c996edf08473dcdb10a58aa12

Checklist

I have read and adhere to the contribution guide.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-08-14T12:59:56Z

Test this change out locally with the following install scripts (Action run 32170321111)

VSCode

Mac/Linux

bash <(curl -Ls https://aka.ms/bicep/nightly-vsix.sh) --run-id 32170321111

Windows

iex "& { $(irm https://aka.ms/bicep/nightly-vsix.ps1) } -RunId 32170321111"

Azure CLI

Mac/Linux

bash <(curl -Ls https://aka.ms/bicep/nightly-cli.sh) --run-id 32170321111

Windows

iex "& { $(irm https://aka.ms/bicep/nightly-cli.ps1) } -RunId 32170321111"

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Adds experimental module documentation generation across Bicep.Core, CLI, and JSON-RPC.

Changes:

Adds typed documentation models and Scriban rendering.
Adds bicep docs generate/output with discovery and atomic writes.
Adds RPC client support, feature configuration, and tests.

Reviewed changes

Copilot reviewed 77 out of 77 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`.gitattributes`	Enforces fixture line endings.
`docs/experimental-features.md`	Documents the feature flag.
`src/Directory.Packages.props`	Adds Scriban version.
`src/vscode-bicep/schemas/bicepconfig.schema.json`	Defines docs feature configuration.
`src/Bicep.Testing/TestFeatureProviderFactory.cs`	Propagates the feature flag.
`src/Bicep.RpcClient/PooledBicepClientFactory.cs`	Forwards pooled documentation requests.
`src/Bicep.RpcClient/Models/Models.cs`	Adds documentation RPC models.
`src/Bicep.RpcClient/IBicepDocumentationClient.cs`	Defines documentation client capability.
`src/Bicep.RpcClient/BicepClient.cs`	Implements documentation RPC calls.
`src/Bicep.RpcClient.Tests/PooledBicepClientFactoryTests.cs`	Tests pooled forwarding.
`src/Bicep.RpcClient.Tests/Files/PublicApis/Azure.Bicep.RpcClient.txt`	Updates public API baseline.
`src/Bicep.RpcClient.Tests/BicepClientUnitTests.cs`	Tests RPC methods and versions.
`src/Bicep.Core/Features/RecordBasedFeatureProvider.cs`	Exposes docs feature state.
`src/Bicep.Core/Features/IFeatureProvider.cs`	Adds feature-provider contract.
`src/Bicep.Core/Features/FeatureProvider.cs`	Reads docs feature configuration.
`src/Bicep.Core/Documentation/Templates/Markdown.scriban`	Provides built-in Markdown rendering.
`src/Bicep.Core/Documentation/IBicepDocumentationGenerator.cs`	Defines generation API.
`src/Bicep.Core/Documentation/BicepDocumentationUsageExample.cs`	Models usage examples.
`src/Bicep.Core/Documentation/BicepDocumentationTypeAnalyzer.cs`	Projects Bicep type metadata.
`src/Bicep.Core/Documentation/BicepDocumentationTemplateLoader.cs`	Resolves template includes.
`src/Bicep.Core/Documentation/BicepDocumentationScriptModelFactory.cs`	Creates the Scriban model.
`src/Bicep.Core/Documentation/BicepDocumentationResourceType.cs`	Models resource types.
`src/Bicep.Core/Documentation/BicepDocumentationReference.cs`	Models module references.
`src/Bicep.Core/Documentation/BicepDocumentationPreset.cs`	Defines rendering presets.
`src/Bicep.Core/Documentation/BicepDocumentationParameter.cs`	Models parameters and discriminators.
`src/Bicep.Core/Documentation/BicepDocumentationOutput.cs`	Models outputs.
`src/Bicep.Core/Documentation/BicepDocumentationOrdering.cs`	Provides deterministic ordering.
`src/Bicep.Core/Documentation/BicepDocumentationModel.cs`	Defines the aggregate docs model.
`src/Bicep.Core/Documentation/BicepDocumentationGenerator.cs`	Builds and renders documentation.
`src/Bicep.Core/Documentation/BicepDocumentationGenerationOptions.cs`	Defines rendering options.
`src/Bicep.Core/Documentation/BicepDocumentationFunction.cs`	Models exported functions.
`src/Bicep.Core/Documentation/BicepDocumentationException.cs`	Defines documentation failures.
`src/Bicep.Core/Documentation/BicepDocumentationExampleDiscovery.cs`	Discovers local examples.
`src/Bicep.Core/Documentation/BicepDocumentationDataCollection.cs`	Models telemetry information.
`src/Bicep.Core/Configuration/ExperimentalFeaturesEnabled.cs`	Adds docs feature configuration.
`src/Bicep.Core/BicepCoreServiceCollectionExtensions.cs`	Registers the generator.
`src/Bicep.Core/Bicep.Core.csproj`	Embeds template and references Scriban.
`src/Bicep.Core.UnitTests/Features/OverriddenFeatureProvider.cs`	Supports feature overrides.
`src/Bicep.Core.UnitTests/Features/FeatureProviderTests.cs`	Tests feature compatibility.
`src/Bicep.Core.UnitTests/Features/FeatureProviderOverrides.cs`	Adds docs override state.
`src/Bicep.Core.UnitTests/Documentation/ThrowingFileExplorer.cs`	Supports I/O failure tests.
`src/Bicep.Core.UnitTests/Documentation/Files/ExpectedMarkdown.md`	Defines Markdown golden output.
`src/Bicep.Core.UnitTests/Documentation/BicepDocumentationTypeAnalyzerTests.cs`	Tests type projection.
`src/Bicep.Core.UnitTests/Documentation/BicepDocumentationTemplateLoaderTests.cs`	Tests include loading.
`src/Bicep.Core.UnitTests/Documentation/BicepDocumentationScriptModelFactoryTests.cs`	Tests Scriban model projection.
`src/Bicep.Core.UnitTests/Documentation/BicepDocumentationOrderingTests.cs`	Tests stable ordering.
`src/Bicep.Core.UnitTests/Documentation/BicepDocumentationGeneratorTests.cs`	Tests model generation and rendering.
`src/Bicep.Core.UnitTests/Documentation/BicepDocumentationExampleDiscoveryTests.cs`	Tests example discovery.
`src/Bicep.Core.UnitTests/Configuration/ConfigurationManagerTests.cs`	Updates configuration expectations.
`src/Bicep.Core.UnitTests/Bicep.Core.UnitTests.csproj`	Embeds Markdown fixtures.
`src/Bicep.Cli/Services/OutputWriter.cs`	Adds atomic file replacement.
`src/Bicep.Cli/Services/DocsModuleScanner.cs`	Resolves modules and outputs.
`src/Bicep.Cli/Services/DocsFileWriter.cs`	Wraps atomic documentation writes.
`src/Bicep.Cli/Services/DocsCommandRunner.cs`	Compiles and renders modules.
`src/Bicep.Cli/Rpc/ICliJsonRpcProtocol.cs`	Defines documentation RPC operations.
`src/Bicep.Cli/Rpc/CliJsonRpcServer.cs`	Implements documentation RPC operations.
`src/Bicep.Cli/Program.cs`	Registers docs commands and services.
`src/Bicep.Cli/Helpers/IServiceCollectionExtensions.cs`	Registers command handlers.
`src/Bicep.Cli/Constants/CliConstants.cs`	Adds docs command constants.
`src/Bicep.Cli/Commands/JsonRpcCommand.cs`	Injects documentation RPC services.
`src/Bicep.Cli/Commands/DocsOutputCommand.cs`	Implements stdout rendering.
`src/Bicep.Cli/Commands/DocsGenerateCommand.cs`	Implements file generation.
`src/Bicep.Cli/Commands/DocsCommand.cs`	Defines the docs command group.
`src/Bicep.Cli/Arguments/DocsOutputArguments.cs`	Defines output arguments.
`src/Bicep.Cli/Arguments/DocsGenerateArguments.cs`	Defines generate arguments.
`src/Bicep.Cli.IntegrationTests/JsonRpcCommandTests.cs`	Tests documentation RPC behavior.
`src/Bicep.Cli.IntegrationTests/HelpTests.cs`	Tests docs help output.
`src/Bicep.Cli.IntegrationTests/Files/DocsCommandTests/Comprehensive/tests/e2e/restricted/main.test.bicep`	Provides test usage example.
`src/Bicep.Cli.IntegrationTests/Files/DocsCommandTests/Comprehensive/templates/custom.scriban`	Provides custom template fixture.
`src/Bicep.Cli.IntegrationTests/Files/DocsCommandTests/Comprehensive/shared/_footer.md`	Provides include fixture.
`src/Bicep.Cli.IntegrationTests/Files/DocsCommandTests/Comprehensive/README.expected.md`	Defines CLI golden output.
`src/Bicep.Cli.IntegrationTests/Files/DocsCommandTests/Comprehensive/modules/logging.bicep`	Provides referenced module fixture.
`src/Bicep.Cli.IntegrationTests/Files/DocsCommandTests/Comprehensive/main.bicep`	Provides comprehensive module fixture.
`src/Bicep.Cli.IntegrationTests/Files/DocsCommandTests/Comprehensive/examples/default/main.bicep`	Provides default usage example.
`src/Bicep.Cli.IntegrationTests/Files/DocsCommandTests/Comprehensive/bicepconfig.json`	Enables docs in fixture.
`src/Bicep.Cli.IntegrationTests/Files/DocsCommandTests/Comprehensive/_header.md`	Provides header include fixture.
`src/Bicep.Cli.IntegrationTests/DocsCommandTests.cs`	Tests CLI generation and failures.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5b6b551b-dfe1-461c-8caa-e9d250df1026

Jared Holgate (jaredfholgate) · 2026-08-15T10:45:16Z

AVM full-registry documentation validation

Validated Bicep PR #20183 commit d92ddae3736c5e54f1f9f9ef4a2d0ad5e8647352 using:

Bicep: Bicep CLI version 0.46.39 (d92ddae373)
Bicep executable SHA256: AEC164970143B703266F2B8696F3019BD145BCCB4B68E674EE4C1E4070B002C4
Azure/bicep-registry-modules commit: 55c62d45eaf6675c09bf663616c3e7fdd8c4560f
573 module entrypoints compared
572 READMEs generated; all 572 matched the checked-in files byte-for-byte
1 module produced no output because avm/ptn/app/container-job-toolkit currently fails Bicep compilation (BCP426, BCP104, BCP287, BCP036)
49 non-error semantic-model differences retained for investigation: 34 parameter-model and 15 example-discovery differences
Duration: 00:07:31.6585443
All checks passed in workflow run 31883321525

Full evidence: summary, validation log, 573-row comparison CSV, and 49-row semantic mismatch report

Evidence file SHA256: 27DE1B5CA5B52F06AE2E2397BA353C9B6CE37E9ECF6C49262950E2142D3775B1

The validated reusable AVM template and no-fallback verifier are tracked in AVM tools PR #67.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5b6b551b-dfe1-461c-8caa-e9d250df1026

Adopt standard output arguments and the shared resolver, remove documentation-only writer and scanner wrappers, and retain deterministic safety and failure behavior across CLI and JSON-RPC. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5b6b551b-dfe1-461c-8caa-e9d250df1026

Keep the template path exception test valid on both Windows and Unix runners. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5b6b551b-dfe1-461c-8caa-e9d250df1026

Jared Holgate (jaredfholgate) · 2026-08-17T14:59:35Z

AVM full-registry documentation validation

Validated Bicep PR #20183 commit 1a1bda32906ecb95bac063670b6ca42e71c0ecaa using:

Bicep: Bicep CLI version 0.46.41 (1a1bda3290)
Bicep executable SHA256: E884EF40E914BA5D4E2B21E4C85F3475D3991240A145E7DF126844FC33B589BB
Azure/bicep-registry-modules commit: 55c62d45eaf6675c09bf663616c3e7fdd8c4560f
573 module entrypoints compared
572 READMEs generated; all 572 matched the checked-in files byte-for-byte
1 module produced no output because avm/ptn/app/container-job-toolkit currently fails Bicep compilation (BCP426, BCP104, BCP287, BCP036)
The failed module's README.md was absent after the run, confirming compilation failures do not leave output
49 non-error semantic-model differences retained for investigation: 34 parameter-model and 15 example-discovery differences
Duration: 00:12:04.7954752

Full evidence (573-row comparison, semantic mismatch report, summary, validation log, and compiler diagnostics):

https://gist.github.com/jaredfholgate/71babd2c996edf08473dcdb10a58aa12

Evidence manifest SHA256: 0DA13A3147259CCAF9FCF3F8775D3DB2FDF14C37F26F17633E5662496582E4EA

The validated reusable AVM template and no-fallback verifier are tracked in AVM tools PR #67.

Add an optional docs config for entrypoints, output, templates, custom values, configurable example sources, and conditional parent-to-child example reassignment across CLI, Core, and JSON-RPC. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5b6b551b-dfe1-461c-8caa-e9d250df1026

Jared Holgate (jaredfholgate) · 2026-08-17T20:18:56Z

Semantic comparison correction

The earlier AVM evidence comment reported 49 unexplained semantic-index differences. That result has now been fully investigated and superseded by validation of commit 4cfde8acfe2257e1a4a751fa86d2aa70d2cb7514:

25 parameter-module mismatches were verifier defects, not product differences. The old index ignored structured discriminator cases and rejected three existing AVM description misspellings. The corrected index now compares those paths successfully.
All 15 example-module mismatches are resolved. The new generic docs configuration was passed to every module call and reassigned tests from four multi-scope parent stubs to their 11 scoped child modules. Ordinary modules retained default discovery behavior.
9 parameter-module differences remain, all as additional paths in the new model; none are missing. Seven come from type information unavailable to the legacy ARM-JSON-based generator (resourceInput<>, tuple-array items, and chained/imported aliases). Two expose names/types/descriptions inside secure object schemas; runtime values are never included. This is intentional and covered by tests.

Final full-registry result:

Bicep: Bicep CLI version 0.46.42 (4cfde8acfe)
Executable SHA256: 84754050AE849DC52B6C11289610C99FD9C20442E38CBD439DA956CE6EBE8D07
573 module entrypoints compared
572 READMEs generated and all 572 matched byte-for-byte
1 known source compilation failure produced no README
9 parameter-model additions
0 example-model mismatches
Duration: 00:11:48.9813665

Updated evidence: https://gist.github.com/jaredfholgate/71babd2c996edf08473dcdb10a58aa12

Evidence manifest SHA256: 5D4E00B7C44BC6B9A8174F89133A93BB2C46BABD1E80BDCC83770AC9BE98248C

The matching docs configuration and verifier are in AVM tools PR #67 at ead76bda2b97eb76d4082e8cc44501aee56604c8.

The byte-parity template still validates rendering and file behavior rather than semantic section reconstruction; the separate corrected semantic index is the evidence for parameter/example coverage.

Document command enablement, every CLI input, configuration schema and precedence, worked JSON examples, discovery reassignment, templates, diagnostics, and the complete template model. Ensure bulk generation emits the experimental disclaimer once after a successful compilation. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5b6b551b-dfe1-461c-8caa-e9d250df1026

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5b6b551b-dfe1-461c-8caa-e9d250df1026

Implement Bicep module documentation generation

e0ff9ef

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Jared Holgate (jaredfholgate) self-assigned this Aug 14, 2026

Jared Holgate (jaredfholgate) added the 📘 Docs Needed label Aug 14, 2026

Make documentation write failures cross-platform

d1b796f

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Jared Holgate (jaredfholgate) requested a balanced review from Copilot August 14, 2026 16:04

Copilot started reviewing on behalf of Jared Holgate (jaredfholgate) August 14, 2026 16:05 View session

Copilot AI reviewed Aug 14, 2026

View reviewed changes

Jared Holgate (jaredfholgate) mentioned this pull request Aug 14, 2026

feat(docs): add AVM documentation parity utility Azure/azure-verified-modules-tools#67

Open