README
¶
bicep-docs
Table of contents
Description
bicep-docs is a command-line tool that generates documentation for Bicep templates.
Installation
Homebrew
brew tap christosgalano/christosgalano
brew install bicep-docs
Go
go install github.com/christosgalano/bicep-docs/cmd/bicep-docs@latest
Binary
Download the latest binary from the releases page.
Requirements
To run bicep-docs, either the Azure CLI or the Bicep CLI must be installed.
| CLI | Minimum Required Version |
|---|---|
| Azure | 2.56.0 |
| Bicep | 0.24.24 |
Currently, you need to modify your bicepconfig.json to enable the userDefinedFunctions feature. More information here.
Usage
bicep-docs is a command-line tool that generates documentation for Bicep templates.
Given an input Bicep file or directory, it parses the file(s) and generates corresponding documentation in Markdown format.
This can be used to automatically create and update documentation for your Bicep templates.
If the input is a directory, then for each main.bicep it will generate a README.md in the same directory. This happens recursively for all subdirectories.
If the input is a Bicep file, the output must be a file; otherwise, an error will be returned.
The default value for the output is README.md, relative to the directory where the command is executed.
CAUTION: If the Markdown file already exists, it will be overwritten.
Example usage
Parse a Bicep file and generate a Markdown file:
bicep-docs --input main.bicep --output readme.md
Parse a Bicep file and generate a README.md file in the same directory:
bicep-docs -i main.bicep
Parse a directory and generate a README.md file for each main.bicep file with verbose output:
bicep-docs -i ./bicep -V
More examples can be found here.
Documentation format
The documentation has the following format:
# module name | file name
## Descripton
...
## Modules
table of modules
## Resources
table of resources
## Parameters
table of parameters
## User Defined Data Types (UDDTs)
table of UDDTs
## User Defined Functions (UDFs)
table of UDFS
## Variables
table of variables
## Outputs
table of outputs
Example documentation file:
storage account
Description
Create a storage account.
Resources
| Symbolic Name | Type | Description |
|---|---|---|
| st | Microsoft.Storage/storageAccounts | This is a test resource. |
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| kind | string | The kind of storage account. | StorageV2 |
| location | string | Location to deploy the storage account. | [resourceGroup().location] |
| name | string | Name of the storage account. | |
| skuName | string | Name of the storage account's sku. | Standard_LRS |
User Defined Data Types (UDDTs)
| Name | Type | Description |
|---|---|---|
| positiveInt | int | Positive integer (> 0). |
User Defined Functions (UDFs)
| Name | Description |
|---|---|
| double | Doubles a positive integer. |
Variables
| Name |
|---|
| test_number |
Outputs
| Name | Type | Description |
|---|---|---|
| doubled | positiveInt (uddt) | Double test_number. |
| resourceId | string | Resource ID of the storage account. |
Bicep folder structure
This tool is extremely useful if you are following this structure for your Bicep projects:
.
├── bicep
│ │
│ ├── modules
│ │ ├── compute
│ │ │ ├── main.bicep
│ │ │ └── README.md
│ │ └── ...
│ │
│ ├── environments
│ │ ├── development
│ │ │ ├── main.bicep
│ │ │ ├── main.bicepparam
│ │ │ └── README.md
│ │ └── ...
Contributing
Information about contributing to this project can be found here.
License
This project is licensed under the MIT License.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
bicep-docs
bicep-docs is a command-line tool that generates documentation for Bicep templates.
|
bicep-docs is a command-line tool that generates documentation for Bicep templates. |
|
internal
|
|
|
cli
Package cli provides a command-line interface (CLI) for the bicep-docs tool, utilizing cobra-cli.
|
Package cli provides a command-line interface (CLI) for the bicep-docs tool, utilizing cobra-cli. |
|
markdown
Package markdown provides functionality to create a Markdown file from a Bicep template.
|
Package markdown provides functionality to create a Markdown file from a Bicep template. |
|
template
Package template provides functions to build and parse Bicep and the corresponding ARM templates.
|
Package template provides functions to build and parse Bicep and the corresponding ARM templates. |
|
types
Package types provides shared types used by multiple packages in the "bicep-docs" application.
|
Package types provides shared types used by multiple packages in the "bicep-docs" application. |