Added optional snippets and badges #31 #30 #42 (#44)

* Added optional snippets and badges #31 #30 #42

* Remove quick start config

* Get option from root path

* Doc improvements based on feedback @vicperdana

Author: BernieWhite

.vscode/settings.json

@@ -22,7 +22,10 @@
         "**/.azure-pipelines/jobs/*.yaml": "azure-pipelines"
     },
     "cSpell.words": [
-        "cmdlet"
+        "Concat",
+        "Quickstart",
+        "cmdlet",
+        "cmdlets"
     ],
     "cSpell.enabledLanguageIds": [
         "csharp",

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+What's changed since pre-release v0.2.0-B2101002:
+
+- New features:
+  - Added the ability to disable parameter file snippet. [#31](https://github.com/Azure/PSDocs.Azure/issues/31)
+    - To disable parameter file snippet set configuration `AZURE_USE_PARAMETER_FILE_SNIPPET`.
+    - See [about_PSDocs_Azure_Configuration] for details.
+  - Added the ability to include badges in template document. [#30](https://github.com/Azure/PSDocs.Azure/issues/30)
+    - Set the `.ps-docs/azure-template-badges.md` file to include badge content.
+    - See [about_PSDocs_Azure_Badges] for details.
+- Engineering:
+  - Bump PSDocs dependency to v0.8.0. [#42](https://github.com/Azure/PSDocs.Azure/issues/42)
+
 ## v0.2.0-B2101002 (pre-release)
 
 What's changed since v0.1.0:
@@ -28,3 +40,6 @@ What's changed since pre-release v0.1.0-B2012006:
 ## v0.1.0-B2012006 (pre-release)
 
 - Initial pre-release.
+
+[about_PSDocs_Azure_Configuration]: docs/concepts/en-US/about_PSDocs_Azure_Configuration.md
+[about_PSDocs_Azure_Badges]: docs/concepts/en-US/about_PSDocs_Azure_Badges.md

README.md

@@ -266,6 +266,23 @@ jobs:
         source_dir: 'out/docs/*'
 ```
 
+## Language reference
+
+PSDocs for Azure extends PowerShell with the following cmdlets and concepts.
+
+### Commands
+
+The following commands exist in the `PSDocs.Azure` module:
+
+- [Get-AzDocTemplateFile](docs/commands/en-US/Get-AzDocTemplateFile.md) - Get Azure template files within a directory structure.
+
+### Concepts
+
+The following conceptual topics exist in the `PSDocs.Azure` module:
+
+- [Badges](docs/concepts/en-US/about_PSDocs_Azure_Badges.md)
+- [Configuration](docs/concepts/en-US/about_PSDocs_Azure_Configuration.md)
+  - [AZURE_USE_PARAMETER_FILE_SNIPPET](docs/concepts/en-US/about_PSDocs_Azure_Configuration.md#azure_use_parameter_file_snippet)
 
 ## Changes and versioning
 

docs/commands/en-US/Get-AzDocTemplateFile.md

@@ -9,7 +9,7 @@ schema: 2.0.0
 
 ## SYNOPSIS
 
-Get Azure template files.
+Get Azure template files within a directory structure.
 
 ## SYNTAX
 

docs/concepts/en-US/about_PSDocs_Azure_Badges.md

@@ -0,0 +1,91 @@
+# PSDocs_Azure_Badges
+
+## about_PSDocs_Azure_Badges
+
+## SHORT DESCRIPTION
+
+Describes how to insert template badges in to documentation.
+
+## LONG DESCRIPTION
+
+PSDocs allows external files to be included in Azure template documentation.
+Commonly this concept is used to include images that represent the validation status of the template.
+These images, are commonly referred to as _badges_.
+PSDocs can include badges that have been generated by an external validation tool.
+
+To include badge markdown:
+
+- Create a sub-directory called `.ps-docs` in the working path of PSDocs.
+This would normally be root directory (`$PWD`) of the repository where your Azure template are stored.
+- Create a file named `azure-template-badges.md` within the `.ps-docs` sub-directory.
+- When creating all files and folder use lower case names.
+
+The contents of this file is automatically inserted in generated output after the title but before description.
+
+### Include badges
+
+To include badge images use standard markdown syntax within the `azure-template-badges.md` file.
+
+> Markdown uses links to reference images.
+> A person viewing the page must have permissions to view the source image.
+> If not, the badge may be shown as a broken or placeholder image.
+
+For example:
+
+```markdown
+![label](https://image_uri)
+```
+
+For example, a Github Actions badge for PSDocs.Azure would be:
+
+```markdown
+![Analyze](https://github.com/Azure/PSDocs.Azure/workflows/Analyze/badge.svg)
+```
+
+To include badges images with a clickable link use standard markdown syntax:
+
+```markdown
+[![label](https://image_uri)](https://link_uri)
+```
+
+For example, an Azure Pipelines badge for PSDocs.Azure would be:
+
+```markdown
+[![Build Status](https://dev.azure.com/PSDocs/PSDocs.Azure/_apis/build/status/PSDocs.Azure-CI?branchName=refs%2Fpull%2F44%2Fmerge)](https://dev.azure.com/PSDocs/PSDocs.Azure/_build/latest?definitionId=1&branchName=refs%2Fpull%2F44%2Fmerge)
+```
+
+### Dynamic links
+
+In additional to inserting static content, some replacement tokens have been defined.
+When specified within `azure-template-badges.md` each token will be replaced when the file is included.
+The following replacement tokens have been defined:
+
+- `{{ template_path }}` - The relative path of the template directory.
+- `{{ template_path_encoded }}` - The relative path of the template directory URL encoded.
+
+For example, if the template path was `.\templates\storage\v1\template.json` the following would be used:
+
+- `{{ template_path }}` = `templates/storage/v1`
+- `{{ template_path_encoded }}` = `templates%2fstorage%2fv1`
+
+The follow example shows source markdown for including badges:
+
+```markdown
+![Best Practice Check](https://azurequickstartsservice.blob.core.windows.net/badges/{{ template_path }}/BestPracticeResult.svg)
+[![Deploy To Azure](https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/1-CONTRIBUTION-GUIDE/images/deploytoazure.svg?sanitize=true)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fazure-quickstart-templates%2Fmaster%2F{{ template_path_encoded }}%2Fazuredeploy.json)
+```
+
+After replacement the following would be the resulting output included in the template document:
+
+```markdown
+![Best Practice Check](https://azurequickstartsservice.blob.core.windows.net/badges/templates/storage/v1/BestPracticeResult.svg)
+[![Deploy To Azure](https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/1-CONTRIBUTION-GUIDE/images/deploytoazure.svg?sanitize=true)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fazure-quickstart-templates%2Fmaster%2Ftemplates%2fstorage%2fv1%2Fazuredeploy.json)
+```
+
+## NOTE
+
+An online version of this document is available at https://github.com/Azure/PSDocs.Azure/blob/main/docs/concepts/en-US/about_PSDocs_Azure_Badges.md.
+
+## KEYWORDS
+
+- Badge

docs/concepts/en-US/about_PSDocs_Azure_Configuration.md

@@ -0,0 +1,61 @@
+# PSDocs_Azure_Configuration
+
+## about_PSDocs_Azure_Configuration
+
+## SHORT DESCRIPTION
+
+Describes PSDocs configuration options specific to `PSDocs.Azure`.
+
+## LONG DESCRIPTION
+
+PSDocs exposes configuration options that can be used to customize execution of document generation.
+This topic describes what configuration options are available.
+
+PSDocs configuration options can be specified by setting the configuration option in `ps-docs.yaml`.
+Additionally, configuration options can be configured in a baseline or set at runtime.
+For details of setting configuration options see [PSDocs options][options]
+
+The following configurations options are available for use:
+
+- [AZURE_USE_PARAMETER_FILE_SNIPPET](#azure_use_parameter_file_snippet)
+
+### AZURE_USE_PARAMETER_FILE_SNIPPET
+
+This configuration option determines if a parameter file snippet is added to documentation.
+By default, a snippet is generated.
+To prevent a parameter file snippet being generated, set this option to `false`.
+
+Syntax:
+
+```yaml
+configuration:
+  AZURE_USE_PARAMETER_FILE_SNIPPET: bool # Either true or false
+```
+
+Default:
+
+```yaml
+# YAML: The default AZURE_USE_PARAMETER_FILE_SNIPPET configuration option
+configuration:
+  AZURE_USE_PARAMETER_FILE_SNIPPET: true
+```
+
+Example:
+
+```yaml
+# YAML: Prevent parameter file snippet from being generated
+configuration:
+  AZURE_USE_PARAMETER_FILE_SNIPPET: false
+```
+
+## NOTE
+
+An online version of this document is available at https://github.com/Azure/PSDocs.Azure/blob/main/docs/concepts/en-US/about_PSDocs_Azure_Configuration.md.
+
+## KEYWORDS
+
+- Configuration
+- Document
+- Snippet
+
+[options]: https://github.com/BernieWhite/PSDocs/blob/main/docs/concepts/PSDocs/en-US/about_PSDocs_Configuration.md

pipeline.build.ps1

@@ -108,7 +108,7 @@ task VersionModule ModuleDependencies, {
     $manifest = Test-ModuleManifest -Path $manifestPath;
     $requiredModules = $manifest.RequiredModules | ForEach-Object -Process {
         if ($_.Name -eq 'PSDocs' -and $Configuration -eq 'Release') {
-            @{ ModuleName = 'PSDocs'; ModuleVersion = '0.7.0' }
+            @{ ModuleName = 'PSDocs'; ModuleVersion = '0.8.0' }
         }
         else {
             @{ ModuleName = $_.Name; ModuleVersion = $_.Version }
@@ -155,8 +155,8 @@ task PSScriptAnalyzer NuGet, {
 
 # Synopsis: Install PSRule
 task PSRule NuGet, {
-    if ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion 1.0.1 -ErrorAction Ignore)) {
-        Install-Module -Name PSRule -Repository PSGallery -MinimumVersion 1.0.1 -Scope CurrentUser -Force;
+    if ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion 1.0.3 -ErrorAction Ignore)) {
+        Install-Module -Name PSRule -Repository PSGallery -MinimumVersion 1.0.3 -Scope CurrentUser -Force;
     }
     if ($Null -eq (Get-InstalledModule -Name PSRule.Rules.MSFT.OSS -MinimumVersion '0.1.0-B2012007' -AllowPrerelease -ErrorAction Ignore)) {
         Install-Module -Name PSRule.Rules.MSFT.OSS -Repository PSGallery -MinimumVersion '0.1.0-B2012007' -AllowPrerelease -Scope CurrentUser -Force;
@@ -166,8 +166,8 @@ task PSRule NuGet, {
 
 # Synopsis: Install PSDocs
 task PSDocs NuGet, {
-    if ($Null -eq (Get-InstalledModule -Name PSDocs -MinimumVersion 0.7.0 -ErrorAction Ignore)) {
-        Install-Module -Name PSDocs -Repository PSGallery -MinimumVersion 0.7.0 -Scope CurrentUser -Force;
+    if ($Null -eq (Get-InstalledModule -Name PSDocs -MinimumVersion 0.8.0 -ErrorAction Ignore)) {
+        Install-Module -Name PSDocs -Repository PSGallery -MinimumVersion 0.8.0 -Scope CurrentUser -Force;
     }
     Import-Module -Name PSDocs -Verbose:$False;
 }

src/PSDocs.Azure/docs/Azure.Template.Doc.ps1

@@ -47,11 +47,7 @@ function global:GetTemplateExample {
             $Path = Join-Path -Path $PWD -ChildPath $Path;
         }
         $template = Get-Content -Path $Path -Raw | ConvertFrom-Json;
-        $normalPath = $Path;
-        if ($normalPath.StartsWith($PWD, [System.StringComparison]::InvariantCultureIgnoreCase)) {
-            $normalPath = $Path.Substring(([String]$PWD).Length);
-            $normalPath = ($normalPath -replace '\\', '/').TrimStart('/');
-        }
+        $normalPath = GetTemplateRelativePath -Path $Path;
         $baseContent = [PSCustomObject]@{
             '$schema'= "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json`#"
             contentVersion = '1.0.0.0'
@@ -68,7 +64,7 @@ function global:GetTemplateExample {
                 continue;
             }
 
-            if ($property.Value.type -eq 'securestring') {
+            if ($property.Value.type -eq 'secureString') {
                 $param = [PSCustomObject]@{
                     reference = [PSCustomObject]@{
                         keyVault = [PSCustomObject]@{
@@ -109,6 +105,27 @@ function global:GetTemplateExample {
     }
 }
 
+# Synopsis: Function to get the relative path of the template
+function global:GetTemplateRelativePath {
+    [CmdletBinding()]
+    [OutputType([String])]
+    param (
+        [Parameter(Mandatory = $True)]
+        [String]$Path
+    )
+    process {
+        if (![System.IO.Path]::IsPathRooted($Path)) {
+            $Path = [System.IO.Path]::Combine($PWD, $Path);
+        }
+        $normalPath = [System.IO.Path]::GetFullPath($Path);
+        if ($normalPath.StartsWith($PWD, [System.StringComparison]::InvariantCultureIgnoreCase)) {
+            $normalPath = $normalPath.Substring(([String]$PWD).Length);
+            $normalPath = $normalPath.Replace('\', '/').TrimStart('/')
+        }
+        return $normalPath;
+    }
+}
+
 # A function to import metadata
 function global:GetTemplateMetadata {
     [CmdletBinding()]
@@ -164,6 +181,17 @@ Document 'README' {
         Title $LocalizedData.DefaultTitle
     }
 
+    # Add badges
+    $relativePath = (Split-Path (GetTemplateRelativePath -Path $templatePath) -Parent).Replace('\', '/').TrimStart('/');
+    $relativePathEncoded = [System.Web.HttpUtility]::UrlEncode($relativePath);
+    Include '.ps-docs/azure-template-badges.md' -ErrorAction SilentlyContinue -BaseDirectory $PWD -Replace @{
+        '{{ template_path }}' = $relativePath
+        '{{ template_path_encoded }}' = $relativePathEncoded
+    }
+
+    Write-Verbose $relativePath
+    Write-Verbose $relativePathEncoded
+
     # Write opening line
     if ($Null -ne $metadata -and [bool]$metadata.PSObject.Properties['description']) {
         $metadata.description
@@ -198,9 +226,15 @@ Document 'README' {
             @{ Name = $LocalizedData.Description; Expression = { $_.Description }}
     }
 
-    # Insert snippet
-    $example = GetTemplateExample -Path $templatePath;
+    # Insert snippets
     Section $LocalizedData.Snippets {
-        $example | Code 'json'
+
+        # Add parameter file snippet
+        if ($PSDocs.Configuration.GetBoolOrDefault('AZURE_USE_PARAMETER_FILE_SNIPPET', $True)) {
+            Section $LocalizedData.ParameterFile {
+                $example = GetTemplateExample -Path $templatePath;
+                $example | Code 'json'
+            }
+        }
     }
 }

src/PSDocs.Azure/en/PSDocs-strings.psd1

@@ -12,4 +12,5 @@
     Type = 'Type'
     Name = 'Name'
     DefaultTitle = 'Azure template'
+    ParameterFile = 'Parameter file'
 }

templates/storage/v1/README.md

@@ -104,6 +104,8 @@ resourceId | string | A unique resource identifier for the storage account.
 
 ## Snippets
 
+### Parameter file
+
 ```json
 {
     "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",