This script/tool is currently being developed by the AVM team and will be made available very soon.
Bicep modules documentation MUST be automatically generated via the provided script/tooling from the AVM team, providing the following headings:
Usage examples for Bicep modules MUST be provided in the following formats:
Bicep file (orchestration module style) - .bicep
module <resourceName> 'br/public:avm/[res|ptn|utl]/<publishedModuleName>:>version<' = {
name: '${uniqueString(deployment().name, location)}-test-<uniqueIdentifier>'
params: { (...) }
}
JSON / ARM Template Parameter Files - .json
Bicep modules MAY provide parameter input examples for parameters using the metadata.example property via the @metadata() decorator.
Example:
@metadata({
example: 'uksouth'
})
@description('Optional. Location for all resources.')
param location string = resourceGroup().location
@metadata({
example: '''
{
keyName: 'myKey'
keyVaultResourceId: '/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/my-rg/providers/Microsoft.KeyVault/vaults/myvault'
keyVersion: '6d143c1a0a6a453daffec4001e357de0'
userAssignedIdentityResourceId '/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/my-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentity'
}
'''
})
@description('Optional. The customer managed key definition.')
param customerManagedKey customerManagedKeyType
It is planned that these examples are automatically added to the module readme’s parameter descriptions when running either the Set-ModuleReadMe or Set-AVMModule scripts (available in the utilities folder).
README documentation MUST be automatically/programmatically generated. MUST include the sections as defined in the language specific requirements BCPNFR2 , TFNFR2 .
An examples/e2e directory MUST exist to provide named scenarios for module deployment.
Where descriptions for variables and outputs spans multiple lines. The description MAY provide variable input examples for each variable using the HEREDOC format and embedded markdown.
Example:
variable "my_complex_input" {
type = map(object({
param1 = string
param2 = optional(number, null)
}))
description = <<DESCRIPTION
A complex input variable that is a map of objects.
Each object has two attributes:
- `param1`: A required string parameter.
- `param2`: (Optional) An optional number parameter.
Example Input:
```terraform
my_complex_input = {
"object1" = {
param1 = "value1"
param2 = 2
}
"object2" = {
param1 = "value2"
}
}
```
DESCRIPTION
}
Terraform modules documentation MUST be automatically generated via Terraform Docs .
A file called .terraform-docs.yml MUST be present in the root of the module and have the following content:
---
### To generate the output file to partially incorporate in the README.md,
### Execute this command in the Terraform module's code folder:
# terraform-docs -c .terraform-docs.yml .
formatter: "markdown document" # this is required
version: "0.16.0"
header-from: "_header.md"
footer-from: "_footer.md"
recursive:
enabled: false
path: modules
sections:
hide: []
show: []
content: |-
{{ .Header }}
<!-- markdownlint-disable MD033 -->
{{ .Requirements }}
{{ .Providers }}
{{ .Resources }}
<!-- markdownlint-disable MD013 -->
{{ .Inputs }}
{{ .Outputs }}
{{ .Modules }}
{{ .Footer }}
output:
file: README.md
mode: replace
template: |-
<!-- BEGIN_TF_DOCS -->
{{ .Content }}
<!-- END_TF_DOCS -->
output-values:
enabled: false
from: ""
sort:
enabled: true
by: required
settings:
anchor: true
color: true
default: true
description: false
escape: true
hide-empty: false
html: true
indent: 2
lockfile: true
read-comments: true
required: true
sensitive: true
type: true