Added support for reading template metadata from metadata.json #32 (#59)

* Added support for reading template metadata from metadata.json #32

* Updates to improve quickstart support #60

Author: BernieWhite

CHANGELOG.md

@@ -8,6 +8,14 @@ What's changed since v0.2.0:
   - Added support for naming document by parent path using conventions. [#43](https://github.com/Azure/PSDocs.Azure/issues/43)
     - Add the `-Convention` parameter with `Azure.NameByParentPath` to use.
     - See [about_PSDocs_Azure_Conventions] for details.
+- General improvements:
+  - Added support for reading template metadata from `metadata.json`. [#32](https://github.com/Azure/PSDocs.Azure/issues/32)
+    - This adds additional compatibility for the Azure Quickstart templates repository.
+    - Additional metadata from `metadata.json` will be read when it exists.
+    - Template metadata take priority over `metadata.json`.
+  - Added support for the `summary` template metadata property. [#60](https://github.com/Azure/PSDocs.Azure/issues/60)
+    - The `summary` template metadata property is intended to provide a short description of the template.
+    - Use the `description` template metadata property to provide a detailed description of the template.
 
 ## v0.2.0
 

README.md

@@ -41,6 +41,8 @@ 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 file
 
 In its simplest structure, an Azure template has the following elements:
@@ -120,7 +122,8 @@ PSDocs supports the following metadata:
 Field | Scope | Type | Description
 ----- | ----- | ---- | -----------
 `name`  | Template | `string` | Used for markdown page title.
-`description` | Template | `string` | Used as the top description for the markdown page.
+`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.
@@ -333,3 +336,4 @@ This project is [licensed under the MIT License](LICENSE).
 [create-workflow]: https://help.github.com/en/articles/configuring-a-workflow#creating-a-workflow-file
 [source-template]: templates/storage/v1/template.json
 [output-template]: templates/storage/v1/README.md
+[FAQ]: docs/features.md#frequently-asked-questions-faq

docs/features.md

@@ -35,3 +35,56 @@ 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](install-instructions.md).
+
+## 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:
+
+1. Metadata is loaded from the template `metadata` property.
+2. When `metadata.json` exists, properties are merged with the template metadata.
+   - Properties included in template metadata override properties included from `metadata.json`.
+   - The `$schema` property from `metadata.json` is ignored.
+   - For PSDocs to discover `metadata.json` it must exist in the same directory as the template file.
+   When creating `metadata.json` use only lowercase in the file name.
+
+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 `name` exists in template metadata, this will take priority over `itemDisplayName` from `metadata.json`.
+- If `name` does not exist in template metadata, `itemDisplayName` from `metadata.json` will 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.
+
+[about_PSDocs_Azure_Badges]: concepts/en-US/about_PSDocs_Azure_Badges.md
+[Azure Resource Manager QuickStart Templates contributing guide]: https://github.com/Azure/azure-quickstart-templates/tree/master/1-CONTRIBUTION-GUIDE#metadatajson

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

@@ -129,15 +129,43 @@ function global:GetTemplateRelativePath {
 # A function to import metadata
 function global:GetTemplateMetadata {
     [CmdletBinding()]
+    [OutputType([Hashtable])]
     param (
         [Parameter(Mandatory = $True)]
         [String]$Path
     )
     process {
+        $metadata = @{};
+
+        # Get metadata from template file
         $template = Get-Content -Path $Path -Raw | ConvertFrom-Json;
         if ([bool]$template.PSObject.Properties['metadata']) {
-            return $template.metadata;
+            foreach ($property in $template.metadata.PSObject.Properties.GetEnumerator()) {
+                $metadata[$property.Name] = $property.Value;
+            }
+        }
+
+        # Get missing metadata from metadata.json
+        $metadataFilePath = Join-Path -Path (Split-Path -Path $Path -Parent) -ChildPath 'metadata.json';
+        if (Test-Path -Path $metadataFilePath) {
+            $extraMetadata = Get-Content -Path $metadataFilePath -Raw | ConvertFrom-Json;
+            foreach ($property in $extraMetadata.PSObject.Properties.GetEnumerator()) {
+
+                if ($property.Name -eq 'itemDisplayName' -and !$metadata.ContainsKey('name')) {
+                    $metadata['name'] = $property.Value;
+                }
+                elseif ($property.Name -eq 'summary' -and !$metadata.ContainsKey('summary')) {
+                    $metadata['summary'] = $property.Value;
+                }
+                elseif ($property.Name -eq 'description' -and !$metadata.ContainsKey('description')) {
+                    $metadata['description'] = $property.Value;
+                }
+                elseif (!$metadata.ContainsKey($property.Name) -and $property.Name -ne '$schema') {
+                    $metadata[$property.Name] = $property.Value;
+                }
+            }
         }
+        return $metadata;
     }
 }
 
@@ -174,13 +202,18 @@ Document 'README' {
     $outputs = GetTemplateOutput -Path $templatePath;
 
     # Set document title
-    if ($Null -ne $metadata -and [bool]$metadata.PSObject.Properties['name']) {
+    if ($Null -ne $metadata -and $metadata.ContainsKey('name')) {
         Title $metadata.name
     }
     else {
         Title $LocalizedData.DefaultTitle
     }
 
+    # Add short description
+    if ($Null -ne $metadata -and $metadata.ContainsKey('summary')) {
+        $metadata.summary
+    }
+
     # Add badges
     $relativePath = (Split-Path (GetTemplateRelativePath -Path $templatePath) -Parent).Replace('\', '/').TrimStart('/');
     $relativePathEncoded = [System.Web.HttpUtility]::UrlEncode($relativePath);
@@ -192,8 +225,8 @@ Document 'README' {
     Write-Verbose $relativePath
     Write-Verbose $relativePathEncoded
 
-    # Write opening line
-    if ($Null -ne $metadata -and [bool]$metadata.PSObject.Properties['description']) {
+    # Add detailed description
+    if ($Null -ne $metadata -and $metadata.ContainsKey('description')) {
         $metadata.description
     }
 

templates/storage/v1/README.md

@@ -2,6 +2,8 @@
 
 Create or update a Storage Account.
 
+This template deploys a Storage Account including blob containers and files shares. Encryption in transit it enabled using a minimum of TLS 1.2.
+
 ## Parameters
 
 Parameter name | Description

templates/storage/v1/template.json

@@ -3,7 +3,8 @@
     "contentVersion": "1.0.0.0",
     "metadata": {
         "name": "Storage Account",
-        "description": "Create or update a Storage Account."
+        "summary": "Create or update a Storage Account.",
+        "description": "This template deploys a Storage Account including blob containers and files shares. Encryption in transit it enabled using a minimum of TLS 1.2."
     },
     "parameters": {
         "storageAccountName": {

tests/PSDocs.Azure.Tests/Azure.QuickStart.Tests.ps1

@@ -38,6 +38,9 @@ Describe 'Templates' -Tag 'QuickStart' {
                     $template = Get-Item -Path $_.TemplateFile;
                     $actualContent = Invoke-PSDocument @invokeParams -OutputPath $outputPath -InputObject $template.FullName -PassThru;
                     $actualContent | Should -BeLike '*!`[Azure Public Test Date`](https://azurequickstartsservice.blob.core.windows.net/badges/template-test/PublicLastTestDate.svg)*';
+                    $actualContent | Should -BeLike "`# Storage Account*";
+                    $actualContent | Should -BeLike "*Create an empty Storage Account.*";
+                    $actualContent | Should -BeLike "*This template deploys a Storage Account including blob containers and files shares. Encryption in transit it enabled using a minimum of TLS 1.2.*";
                     $actualContent;
                 }
                 $result | Should -Not -BeNullOrEmpty;

tests/PSDocs.Azure.Tests/template-test/metadata.json

@@ -0,0 +1,9 @@
+{
+    "$schema": "https://aka.ms/azure-quickstart-templates-metadata-schema#",
+    "itemDisplayName": "Storage Account",
+    "description": "This template deploys an creates a Storage Account in an Azure subscription.",
+    "summary": "Create an empty Storage Account.",
+    "githubUsername": "BernieWhite",
+    "type": "QuickStart",
+    "dateUpdated": "2021-03-11"
+}

tests/PSDocs.Azure.Tests/template-test/template.json

@@ -2,8 +2,7 @@
     "$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."
+        "description": "This template deploys a Storage Account including blob containers and files shares. Encryption in transit it enabled using a minimum of TLS 1.2."
     },
     "parameters": {
         "storageAccountName": {