Generate markdown from Azure infrastructure as code (IaC) artifacts.
This is a monorepo containing the complete PSDocs ecosystem:
| Package | Description | Location |
|---|---|---|
| PSDocs | Core documentation engine | packages/psdocs/ |
| PSDocs.Azure | Azure IaC documentation generator | packages/psdocs-azure/ |
| VS Code Extension | PSDocs extension for VS Code | packages/vscode-extension/ |
# Build all packages
./build.ps1 -Build
# Build and test specific package
./build.ps1 -Package psdocs-azure -Build -Test
# Build VS Code extension
./build.ps1 -Package vscode -BuildEach component is versioned independently using prefixed tags:
- PSDocs:
psdocs-v{version}(e.g.,psdocs-v0.10.0) - PSDocs.Azure:
psdocs-azure-v{version}(e.g.,psdocs-azure-v0.4.0) - VS Code Extension:
vscode-v{version}(e.g.,vscode-v1.1.0)
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.
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, please check the project GitHub issues page instead.
Support for this project/ product is limited to the resources listed above.
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 / instructions |
The follow example uses PSDocs for Azure to generate markdown from an Azure template. The source template and generated output are provided below.
For frequently asked questions, see the FAQ.
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.
To run PSDocs for Azure locally use the Invoke-PSDocument cmdlet.
# Import moduleImport-Module PSDocs.Azure;
# Generate markdownInvoke-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).
To scan for templates in a directory the Get-AzDocTemplateFile cmdlet can be used.
# Import moduleImport-Module PSDocs.Azure;
# Scan for Azure template file recursively in the templates/ directoryGet-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 markdownInvoke-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
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.
- 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.yamljobs:
- 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@4displayName: 'Copy files to a storage account blob container'inputs:
SourcePath: 'out/docs/*'azureSubscription: 'psdocstest'Destination: 'AzureBlob'storage: '<storageaccountname>'ContainerName: 'ps-docs'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 to create an empty workflow file.
- Add a PowerShell step to:
- Install PSDocs.Azure 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
STORAGEACCOUNTSECRETaction 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.yamlname: Generate ARM templates docson:
push:
branches: [ main ]jobs:
arm_docs:
name: Generate ARM template docsruns-on: ubuntu-lateststeps:
- name: Checkoutuses: actions/checkout@v2# STEP 1: Generate Markdowns using PSDocs
- name: Generate ARM markdownsrun: | 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; }shell: pwsh# STEP 2: Copy files to a storage account
- name: Copy files to a storage accountuses: bacongobbler/azure-blob-storage-upload@v1.1.1with:
connection_string: ${{ secrets.STORAGEACCOUNTSECRET }}container_name: ps-docssource_dir: 'out/docs/*'PSDocs for Azure extends PowerShell with the following cmdlets and concepts.
The following commands exist in the PSDocs.Azure module:
- Get-AzDocTemplateFile - Get Azure template files within a directory structure.
The following conceptual topics exist in the PSDocs.Azure module:
Modules in this repository will use the semantic versioning model to declare breaking changes from v1.0.0. Prior to v1.0.0, breaking changes may be introduced in minor (0.x.0) version increments. For a list of module changes please see the change log.
Pre-release module versions are created on major commits and can be installed from the PowerShell Gallery. Pre-release versions should be considered experimental. Modules and change log details for pre-releases will be removed as standard releases are made available.
For maintainers cutting a release, see RELEASING.md.
This project welcomes contributions and suggestions. If you are ready to contribute, please visit the contribution guide.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
This project is licensed under the MIT License.