PSDocs for Azure

Generate markdown from Azure infrastructure as code (IaC) artifacts.

![ci-badge]

Features of PSDocs for Azure include:

• Ready to go - Use pre-built templates.
• DevOps - Generate within a continuous integration (CI) pipeline.
• Cross-platform - Run on MacOS, Linux, and Windows.

Support

This project uses GitHub Issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates.

• For new issues, file your bug or feature request as a new [issue].
• For help, discussion, and support questions about using this project, join or start a [discussion].

If you have any problems with the [PSDocs][engine] engine, please check the project GitHub issues page instead.

Support for this project/ product is limited to the resources listed above.

Getting the modules

This project requires the PSDocs PowerShell module. For details on each see [install].

You can download and install these modules from the PowerShell Gallery.

Module | Description | Downloads / instructions ------ | ----------- | ------------------------ PSDocs.Azure | Generate documentation from Azure infrastructure as code (IaC) artifacts. | [latest][module] / [instructions][install]

Getting started

The follow example uses PSDocs for Azure to generate markdown from an Azure template. The source template and generated output are provided below.

• [Azure template][source-template]
• [Output markdown][output-template]

For frequently asked questions, see the [FAQ].

Annotate templates files

In its simplest structure, an Azure template has the following elements:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {  },
  "variables": {  },
  "functions": [  ],
  "resources": [  ],
  "outputs": {  }
}

Additionally a metadata property can be added in most places throughout the template. For example:

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "metadata": {
        "name": "Storage Account",
        "description": "Create or update a Storage Account."
    },
    "parameters": {
        "storageAccountName": {
            "type": "string",
            "metadata": {
                "description": "The name of the Storage Account."
            }
        },
        "tags": {
            "type": "object",
            "metadata": {
                "description": "Tags to apply to the resource.",
                "example": {
                    "service": "<service_name>",
                    "env": "prod"
                }
            }
        }
    },
    "resources": [
    ],
    "outputs": {
        "resourceId": {
            "type": "string",
            "value": "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]",
            "metadata": {
                "description": "A unique resource identifier for the storage account."
            }
        }
    }
}

This metadata and the template structure itself can be used to dynamically generate documentation. Documenting templates in this way allows you to:

• Include meaningful information with minimal effort.
• Use DevOps culture to author infrastructure code and documentation side-by-side.
  • Review pull requests (PR) with changes and documentation together.
  • Use continuous integration and deployment to release changes.
• Keep documentation up-to-date. No separate wiki or document to keep in sync.

PSDocs interprets the template structure and metadata to generate documentation as markdown. Generating documentation as markdown allows you to publish web-based content on a variety of platforms.

PSDocs supports the following metadata:

Field | Scope | Type | Description ----- | ----- | ---- | ----------- name | Template | string | Used for markdown page title. summary | Template | string | Used as a short description for the markdown page. description | Template | string | Used as a detailed description for the markdown page. description | Parameter | string | Used as the description for the parameter. example | Parameter | string, boolean, object, or array | An example use of the parameter. The example is included in the JSON snippet. If an example is not included the default value is used instead. ignore | Parameter | boolean | When true the parameter is not included in the JSON snippet. description | Output | string | Used as the description for the output.

An example of an Azure Storage Account template with metadata included is available [here][source-template].

Running locally

To run PSDocs for Azure locally use the Invoke-PSDocument cmdlet.

# Import module
Import-Module PSDocs.Azure;

# Generate markdown
Invoke-PSDocument -Module PSDocs.Azure -InputObject '<template_file_path>' -OutputPath out/docs/;

This will generate a README.md in out/docs directory with the generated markdown (also creates out/docs/ directory if it does not exist).

Scanning for templates

To scan for templates in a directory the Get-AzDocTemplateFile cmdlet can be used.

# Import module
Import-Module PSDocs.Azure;

# Scan for Azure template file recursively in the templates/ directory
Get-AzDocTemplateFile -Path templates/ | ForEach-Object {
    # Generate a standard name of the markdown file. i.e. <name>_<version>.md
    $template = Get-Item -Path $_.TemplateFile;
    $templateName = $template.Directory.Parent.Name;
    $version = $template.Directory.Name;
    $docName = "$($templateName)_$version";

    # Generate markdown
    Invoke-PSDocument -Module PSDocs.Azure -OutputPath out/docs/ -InputObject $template.FullName -InstanceName $docName;
}

In this example template files are stored in a directory structure such as templates/<name>/<version>/template.json. i.e. templates/storage/v1/template.json.

The example finds all the Azure template files and outputs a markdown file for each in out/docs/. An example of the generated markdown is available [here][output-template]

Using with Azure Pipelines

The following example shows how to setup Azure Pipelines to generate ARM template documentation in the markdown format. This example copies the generated markdown files to a designated blob storage.

• Create a new YAML pipeline with the Starter pipeline template.
• Add a PowerShell task to:
  • Install [PSDocs.Azure][module] module.
  • Scan for Azure template file recursively in the templates/ directory.
  • Generate a standard name of the markdown file. i.e. <name>_<version>.md
  • Generate the markdown to a specific directory.
• Add an AzureFileCopy task to copy the generated markdown to an Azure Storage Blob container.

For example:

# Example: .azure-pipelines/psdocs-blobstorage.yaml

jobs:
- job: 'generate_arm_template_documentation'
  displayName: 'Generate ARM template docs'
  pool:
    vmImage: 'windows-2019'
  steps:
  # STEP 1: Generate Markdowns using PSDocs
  - powershell: | 
      Install-Module -Name 'PSDocs.Azure' -Repository PSGallery -force;
        # Scan for Azure template file recursively in the templates/ directory
        Get-AzDocTemplateFile -Path templates/ | ForEach-Object {
        # Generate a standard name of the markdown file. i.e. <name>_<version>.md
        $template = Get-Item -Path $_.TemplateFile;
        $templateName = $template.Directory.Parent.Name;
        $version = $template.Directory.Name;
        $docName = "$($templateName)_$version";
        # Generate markdown
        Invoke-PSDocument -Module PSDocs.Azure -OutputPath out/docs/ -InputObject $template.FullName -InstanceName $docName;
      }
    displayName: 'Export template data'
    
  # STEP 2: Copy files to a storage account
  - task: AzureFileCopy@4
    displayName: 'Copy files to a storage account blob container'
    inputs:
      SourcePath: 'out/docs/*'
      azureSubscription: 'psdocstest'
      Destination: 'AzureBlob'
      storage: '<storageaccountname>' 
      ContainerName: 'ps-docs'

Using with GitHub Actions

The following example shows how to setup GitHub Actions to copy generated markdown files to an Azure blob storage account.

• See [Creating a workflow file][create-workflow] to create an empty workflow file.
• Add a PowerShell step to:
  • Install [PSDocs.Azure][module] module.
  • Scan for Azure template file recursively in the templates/ directory.
  • Generate a standard name of the markdown file. i.e. <name>_<version>.md
  • Generate the markdown to a specific directory.
• Set the STORAGEACCOUNTSECRET action secret.
• Use an Azure Blob Storage Upload action to copy the generated markdown to an Azure Storage Blob container.

For example:

# Example: .github/workflows/arm-docs.yaml

name: Generate ARM templates docs
on:
  push:
    branches: [ main ]
jobs:
  arm_docs:
    name: Generate ARM template docs
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v2
    # STEP 1: Generate Markdowns using PSDocs
    - name: Generate ARM markdowns
      run: | 
        Install-Module -Name 'PSDocs.Azure' -Repository PSGallery -force;
        # Scan for Azure template file recursively in the templates/ directory
        Get-AzDocTemplateFile -Path templates/ | ForEach-Object {
          # Generate a standard name of the markdown file. i.e. <name>_<version>.md
          $template = Get-Item -Path $_.TemplateFile;
          $templateName = $template.Directo