What is PSDocs for Azure?#
PSDocs for Azure is a module for PSDocs, an engine to generate documentation from Infrastructure as Code (IaC). PSDocs for Azure includes pre-built functions and templates that make it easy to generate documentation.
What customers about PSDocs for Azure:
- Continuous — Generate documentation as an output of infrastructure code, not an extra process that someone needs to do.
- Consistency — Focus on building great solutions on Azure with infrastructure code. As infrastructure code is updated so is the documentation.
-
Consumable — Transform infrastructure code into presentable documentation. Use standard documentation that make it easier to deploy Azure resources.
Ready to go#
PSDocs for Azure automatically generates documentation for Azure infrastructure as code (IaC) artifacts. It does this by, reading then processing each artifacts with one or more included documentation templates. Documentation is outputted as markdown a standard, easy to read, easy to render format for modern documentation. We use the same standard for docs.microsoft.com.
Currently the following infrastructure code artifacts are supported:
- Azure Resource Manager (ARM) template files. Example output.
As new features are added and improved, download the latest PowerShell module to start using them.
DevOps#
Azure infrastructure code such as ARM template supports a number of ways to self document in code. PSDocs uses these existing features and makes them easier to consume.
Document generation can be integrated into a continuous integration (CI) pipeline to:
- Shift-left: Identify documentation issues and provide fast feedback in pull requests.
Cross-platform#
PSDocs uses modern PowerShell libraries at its core, allowing it to go anywhere PowerShell can go. PSDocs runs on MacOS, Linux and Windows.
PowerShell makes it easy to integrate PSDocs into popular CI systems.
To install, use the Install-Module cmdlet within PowerShell.
For installation options see install instructions.
Frequently Asked Questions (FAQ)#
Can PSDocs read from metadata.json?#
The Azure Quickstart Templates repository uses an additional metadata.json to store template metadata.
PSDocs doesn't require a metadata.json file to exist but will fallback to this file if it exists.
For details on metadata.json see Azure Resource Manager QuickStart Templates contributing guide.
PSDocs reads metadata.json using the following logic:
- Metadata is loaded from the template
metadataproperty. - When
metadata.jsonexists, properties are merged with the template metadata.- Properties included in template metadata override properties included from
metadata.json. - The
$schemaproperty frommetadata.jsonis ignored. - For PSDocs to discover
metadata.jsonit must exist in the same directory as the template file. When creatingmetadata.jsonuse only lowercase in the file name.
- Properties included in template metadata override properties included from
The schema of metadata.json differs from template metadata.
To maintain compatibility, PSDocs automatically maps the metadata as described in the following table.
| metadata.json | Template metadata | Description | |
|---|---|---|---|
itemDisplayName |
Maps to | name |
Used for markdown page title. |
summary |
Maps to | summary |
Used as a short description for the markdown page. |
description |
Maps to | description |
Used as a detailed description for the markdown page. |
For example:
- If
nameexists in template metadata, this will take priority overitemDisplayNamefrommetadata.json. - If
namedoes not exist in template metadata,itemDisplayNamefrommetadata.jsonwill be used.
How do I include a badge image?#
To include a badge image, create the .ps-docs/azure-template-badges.md file.
Within this file add markdown links to your badge image.
Use the following placeholders to reference unique images per template.
{{ template_path }}- The relative path of the template directory.{{ template_path_encoded }}- The relative path of the template directory URL encoded.
See about_PSDocs_Azure_Badges for additional details.
Can PSDocs generate badges for documentation?#
No. PSDocs can not generate badge images for you.
Once you have generated a badge, PSDocs can include a link to the badge for displaying directly in markdown.