Skip to content

Instantly share code, notes, and snippets.

@dariuszparys

dariuszparys/generate-bicep-documentation.ps1

Created May 29, 2024 09:18
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save dariuszparys/c8ed13e70295340b90c1c46ebab4eea2 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save dariuszparys/c8ed13e70295340b90c1c46ebab4eea2 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
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
Raw
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

Parameter Setting

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

skuName

Parameter Setting

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

Parameter Setting

  • Default value: [resourceGroup().location]

tags

Parameter Setting

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"
            }
        }
    }
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment