Updated output spec - #67
Conversation
| ## Object output | ||
| The following declares an object output that returns information about the resourceGroup: | ||
| ``` | ||
| output myResourceGroup = resourceGroup() |
There was a problem hiding this comment.
isn't the type missing? I would have thought this would be:
output myResourceGroup object = resourceGroup() #Resolved
There was a problem hiding this comment.
Yes, I forgot the type ☹ #Resolved
There was a problem hiding this comment.
Curious do we allow implicit type inferring when it's not ambiguous? #Resolved
There was a problem hiding this comment.
On variables we infer the type. On parameters, we don't because the value isn't there. On outputs we could infer it because there's a required value., but I see outputs as part of the contract. The extra type check comparing the type of value with the declared type of the output will guard against user errors like accidentally assigning the wrong type of value due to an expression typo. (var has issues like that in certain cases in c#, for example.)
In reply to: 451719936 [](ancestors = 451719936)
| ## Boolean output | ||
| The following declares a boolean output value and sets the value using an expression. | ||
| ``` | ||
| output isInputParamEmpty = length(myParam) == 0 |
There was a problem hiding this comment.
same here - should this be:
output isInputParamEmptry boolean = length(myParam) == 0 #Resolved
There was a problem hiding this comment.
Will add it back. #Resolved
There was a problem hiding this comment.
|
Another thing, do we allow output declarations to scatter in a bicep file? Can we clarify that in the spec? #Resolved |
We do allow these to be scattered to support easier copy/paste of code blocks (e.g. I create a resource and want to output a property from that resource) Clarifying it in the spec would be good, I took a quick glance and we don't have anything in the spec on "general structure" that would describe things like "params, vars, resources, outputs, modules can be declared anywhere in the document" or "identifiers can be referenced directly e.g. |
|
Yeah, they can be scattered like everything else. I'll add something to the spec. In reply to: 655682992 [](ancestors = 655682992) |
|
Fixed. In reply to: 655684207 [](ancestors = 655684207,655682992) |
|
|
||
| Parameter declarations will be compiled into ARM template parameters. See [Template Parameter Syntax Reference](https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/template-syntax#parameters) for more information. | ||
|
|
||
| There are no constraints on placement of parameter declarations. They be mixed with any other valid declarations in any order and they do not have to appear at the top of the file. |
There was a problem hiding this comment.
That's what I get for sending updates in a meeting.
|
|
||
| Unlike [parameters](./parameters.md) or [outputs](./outputs.md), variables do not require declaring the type. The type is inferred from the value of the variable. | ||
|
|
||
| There are no constraints on placement of variable declarations. They be mixed with any other valid declarations in any order. |
There was a problem hiding this comment.
Fixing...
## Description Adds the experimental `bicep docs generate` command, which renders module documentation from Bicep's semantic model plus discovered usage examples through [Scriban](https://github.com/scriban/scriban). Implements [REP 0025: Module documentation generation commands](https://github.com/Azure/bicep-reps/blob/main/active/0025-module-documentation-generation.md) and supersedes [#19694](#19694). The validated AVM templates, root configuration, semantic verifier, and full-repository runner are in [Azure/azure-verified-modules-tools PR #67](Azure/azure-verified-modules-tools#67). ## Example usage ```powershell # 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 ```json { "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`](https://github.com/Azure/bicep/blob/jaredfholgate-bicep-docs-generation/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 - [x] I have read and adhere to the [contribution guide](https://github.com/Azure/bicep/blob/main/CONTRIBUTING.md). --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5b6b551b-dfe1-461c-8caa-e9d250df1026
3 participants
Updated output spec to reflect team consensus regarding the syntax.