BicepDocs is currently under development. Please report issues you find. Also see the list of known issues before reporting.
Bicepdocs is not endorsed or affiliated with Microsoft
BicepDocs is a tool to build documentation for Bicep modules. It aims to provide a way to easily document your custom modules without having to manually maintain and update documentation.
See a quick example for the bicep file that has been converted to a markdown file using the markdown formatter.
Check the Roadmap for planned features and changes.
To generate documentation from modules on the file system
bicepdocs generate filesystem \
--folderPath "path-to-input-folder" \
--out "path-to-write-files-to" \
--formatter markdown \
[--config "path-to-config-file"]
Using Homebrew:
# Add the bicepdocs tap
brew tap joachimdalen/bicepdocs
# Install bicepdocs
brew install bicepdocs
Using BASH:
# Get the latest released binary
curl -Lo bicepdocs https://github.com/joachimdalen/bicepdocs/releases/latest/download/bicepdocs-osx-x64
# Make the file executable
chmod +x ./bicepdocs
# Add Gatekeeper exception (requires admin)
sudo spctl --add ./bicepdocs
# Add the executable to your PATH
sudo mv ./bicepdocs /usr/local/bin/bicepdocs
# Verify the installation
bicepdocs --help
# Get the latest released binary
curl -Lo bicepdocs https://github.com/joachimdalen/bicepdocs/releases/latest/download/bicepdocs-linux-x64
# Make the file executable
chmod +x ./bicepdocs
# Add the executable to your PATH
sudo mv ./bicepdocs /usr/local/bin/bicepdocs
# Verify the installation
bicepdocs --help
Other installation methods are planned: Improve installation experience for Windows users
Using Powershell:
# Create the install folder
$installPath = "$env:USERPROFILE\.bicepdocs"
$installDir = New-Item -ItemType Directory -Path $installPath -Force
$installDir.Attributes += 'Hidden'
# Get the latest released binary
(New-Object Net.WebClient).DownloadFile("https://github.com/joachimdalen/bicepdocs/releases/latest/download/bicepdocs-win-x64.exe", "$installPath\bicepdocs.exe")
# Add the executable to your PATH
$currentPath = (Get-Item -path "HKCU:\Environment" ).GetValue('Path', '', 'DoNotExpandEnvironmentNames')
if (-not $currentPath.Contains("%USERPROFILE%\.bicepdocs")) { setx PATH ($currentPath + ";%USERPROFILE%\.bicepdocs") }
if (-not $env:path.Contains($installPath)) { $env:path += ";$installPath" }
# Verify the installation
bicepdocs --help
The source is responsible for fetching the bicep files and providing the Formatter with the text representation of the file.
Source | Description |
---|---|
filesystem | Loads bicep files from the file system |
The formatter is responsible for converting the bicep file into the wanted documentation format. Currently all formatters is based on markdown.
Formatter | Description |
---|---|
markdown | Converts bicep files and formats them as markdown |
docusaurus | Converts bicep files and formats them as markdown while adding metadata and files for Docusaurus |
The destination takes the formatted documentation file and writes it to the wanted location.
Destination | Description |
---|---|
filesystem | Writes the formatted files to the file system |
In certain situations you want to append metadata to your module files. This metadata can be provided to the documentation by adding the following metadata
definition to your module. The keyword can be changed in the configuration file.
metadata moduleDocs = {
title: 'The title of the module'
description: 'A description describing the module'
version: '2022-12-16' // The version will also be used to determine the folder structure
owner: 'Some User <some.user@email.com>'
}
Certain options can be configured using a yaml file. For full reference, see the example-config.yml. Provide the file path to the configuration file using the global paramter --config
Option | Description |
---|---|
includeExistingResources |
When true will include referenced resources using the existing keyword in the resources list |
metaKeyword |
Metadata definition keyword used for module metadata |
includeParameters |
Include the parameters section |
includeUsage |
Include the code example /usage section |
includeResources |
Include the list of resources |
includeOutputs |
Inlude the outputs section |
sectionOrder |
Section order for the generated document |
disableVersioning |
Do not generate versioned output folders |
formatters |
Options for the individual formatters. See the documentation for the formatter for more information |