bicep docs
1.2.0
Description
Installation
Requirements
Usage
Contributing
License
bicep-docs is a command-line tool that generates documentation for Bicep templates.
brew tap christosgalano/christosgalano brew install bicep-docs
go install github.com/christosgalano/bicep-docs/cmd/bicep-docs@latest
Download the latest binary from the releases page.
To run bicep-docs, either the Azure CLI or the Bicep CLI must be installed.
| CLI | Minimum Required Version |
|---|---|
| Azure | 2.64.0 |
| Bicep | 0.29.0 |
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.
Regarding the arguments --include-sections and --exclude-sections, the available sections are: description, usage, modules, resources, parameters, udfs, uddts, variables, outputs.
The default sections ordered are description,usage,modules,resources,parameters,udfs,uddts,variables,outputs. The default input for--exclude-sections is ''. This ensures backward compatibility with the previous version.
The order of the sections is respected when including them.
When excluding sections, the result will be the default sections minus the excluded ones (e.g. --exclude-sections description,usage will include modules,resources,parameters,udfs,uddts,variables,outputs in that order).
Both arguments cannot be provided at the same time, unless the --include-sections argument is the same as the default sections (e.g. --include-sections description,usage,modules,resources,parameters,udfs,uddts,variables,outputs).
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
Parse a Bicep file and generate a README.md excluding the user-defined sections:
bicep-docs --input main.bicep --exclude-sections udfs,uddts
Parse a Bicep file and generate a README.md including only the resources and modules in that order:
bicep-docs ---input main.bicep --include-sections resources,modules
More examples can be found here.
The documentation has the following format:
# module name | file name## Description...## Usage...## Modulestable of modules## Resourcestable of resources## Parameterstable of parameters## User Defined Data Types (UDDTs)table of UDDTs## User Defined Functions (UDFs)table of UDFS## Variablestable of variables## Outputstable of outputs
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
│ │ └── ...Information about contributing to this project can be found here.
This project is licensed under the MIT License.
