generate-bicep-documentation.ps1

<#
.SYNOPSIS
This script compiles Bicep files to ARM templates and generates corresponding documentation.

.DESCRIPTION
The script takes in a directory of Bicep files, compiles them into ARM templates and then generates markdown documentation for each ARM template.
The markdown files are then merged into a single file and copied to the destination path provided.

.PARAMETER BicepDirectory
Specifies the directory containing Bicep files. This parameter is mandatory.

.PARAMETER DestinationFile
Specifies the destination path including the filename where the final merged documentation markdown file will be copied. This parameter is mandatory.

.EXAMPLE
PS> .\Script.ps1 -BicepDirectory "path\to\bicep\files" -DestinationFile "path\to\destination"

#>
param (
    [Parameter(Mandatory=$true)] [string] $BicepDirectory,
    [Parameter(Mandatory=$true)] [string] $DestinationFile
)

$compiledDir = "$BicepDirectory/.generated/arm"
$docDir = "$BicepDirectory/.generated/docs"
$mergedMdFilename = "MergedDocumentation.md"

if (!(Test-Path $compiledDir)) {
    New-Item -ItemType Directory -Force -Path $compiledDir
}

if (!(Test-Path $docDir)) {
    New-Item -ItemType Directory -Force -Path $docDir
}

$bicepDir = Resolve-Path $BicepDirectory

Get-ChildItem -Path $bicepDir -Filter "*.bicep" -Recurse | ForEach-Object {
    $jsonFileName = $_.BaseName + '.json'
    $relativeDir = [IO.Path]::GetRelativePath($bicepDir.Path, $_.DirectoryName)
    if (!(Test-Path "$compiledDir/$relativeDir")) {
        New-Item -ItemType Directory -Force -Path "$compiledDir/$relativeDir"
    }
    Write-Host "Attempting to compile Bicep file to ARM template..."
    try {
        & 'bicep' 'build' $_.FullName '--outfile' "$compiledDir/$relativeDir/$jsonFileName"
        Write-Host "Successfully compiled Bicep file to ARM template: $compiledDir/$relativeDir/$jsonFileName"
    }
    catch {
        Write-Host "Failed to compile Bicep file: $_"
        continue
    }
}

$compiledDir = Resolve-Path $compiledDir
Get-ChildItem -Path $compiledDir -Filter '*.json' -Recurse | ForEach-Object {
    $markdownFileName = $_.BaseName
    $relativeDir = [IO.Path]::GetRelativePath($compiledDir, $_.DirectoryName)
    if (!(Test-Path "$docDir/$relativeDir")) {
        New-Item -ItemType Directory -Force -Path "$docDir/$relativeDir"
    }
    try {
        Invoke-PSDocument -Module PSDocs.Azure -OutputPath "$docDir/$relativeDir" -InputObject $_.FullName -Culture 'en-US' -InstanceName $markdownFileName;
    }
    catch {
        Write-Host "Error generating documentation for $($_.FullName): $_"
    }
}

$mergedMarkdownFile = Join-Path -Path (Resolve-Path $docDir) -ChildPath $mergedMdFilename
New-Item -ItemType File -Force -Path $mergedMarkdownFile
Get-ChildItem -Path $docDir -Filter "*.md" -Recurse | ForEach-Object {
    $content = Get-Content $_.FullName
    Add-Content -Path $mergedMarkdownFile -Value $content
}

$destinationDir = Split-Path -Path $DestinationFile -Parent
if(!(Test-Path -Path $destinationDir)) {
    New-Item -Path $destinationDir -ItemType Directory -Force
}
Copy-Item -Path $mergedMarkdownFile -Destination $DestinationFile

storage.md

Simple Storage Module

This storage module is used for non critical business data.

Parameters

Parameter name	Required	Description
storageAccountName	Yes	Storage account name must be between 3 and 24 characters in length and use numbers and lower-case letters only.
skuName	No	Please talk with the subscription owner if a different SKU is needed
location	No
tags	No	Please specify here an object that includes the environment and the owner of the corresponding resource. See the example

storageAccountName

Storage account name must be between 3 and 24 characters in length and use numbers and lower-case letters only.

skuName

Please talk with the subscription owner if a different SKU is needed

• Default value: Standard_LRS

• Allowed values: Standard_LRS, Standard_GRS, Standard_RAGRS, Standard_ZRS, Premium_LRS

location

• Default value: [resourceGroup().location]

tags

Please specify here an object that includes the environment and the owner of the corresponding resource. See the example

• Default value: @{env=dev; owner=foo}

Outputs

Name	Type	Description
name	string	Name of the storage account created. Can be used to reference the resource

Snippets

Parameter file

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "metadata": {
        "template": "base/.generated/arm/storage.json"
    },
    "parameters": {
        "storageAccountName": {
            "value": ""
        },
        "skuName": {
            "value": "Standard_LRS"
        },
        "location": {
            "value": "[resourceGroup().location]"
        },
        "tags": {
            "value": {
                "env": "dev",
                "owner": "bar"
            }
        }
    }
}