Added support for naming document by parent path using conventions #43 (#58)

* Added support for naming document by parent path using conventions #43

* Added updates based on feedback

Author: BernieWhite

CHANGELOG.md

@@ -2,7 +2,15 @@
 
 ## Unreleased
 
+What's changed since v0.2.0:
+
+- New Features:
+  - 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.
+
 ## v0.2.0
+
 What's changed since v0.1.0:
 
 - New Features:
@@ -16,20 +24,21 @@ What's changed since v0.1.0:
     - Set the `.ps-docs/azure-template-badges.md` file to include badge content.
     - See [about_PSDocs_Azure_Badges] for details.
   - Template outputs are added to generated document. [#28](https://github.com/Azure/PSDocs.Azure/issues/28)
-
+- General Improvements
+  - Minor update to the documentation to include OutputPath to generate README.md [#50](https://github.com/Azure/PSDocs.Azure/issues/50)
+- Engineering:
+  - Bump PSDocs dependency to v0.8.0. [#42](https://github.com/Azure/PSDocs.Azure/issues/42)
 - Bug fixes:
   - Fixed snippet with short relative template causes exception. [#26](https://github.com/Azure/PSDocs.Azure/issues/26)
   - Fixed cannot bind argument when metadata name is not set. [#35](https://github.com/Azure/PSDocs.Azure/issues/35)
 
-- Engineering:
-  - Bump PSDocs dependency to v0.8.0. [#42](https://github.com/Azure/PSDocs.Azure/issues/42)
+What's changed since pre-release v0.2.0-B2102012:
 
-- General Improvements
-  - Minor update to the documentation to include OutputPath to generate README.md [#50](https://github.com/Azure/PSDocs.Azure/issues/50)
+- No additional changes.
 
 ## v0.2.0-B2102012 (pre-release)
 
-What's changed since pre-release v0.2.0-B2102012:
+What's changed since pre-release v0.2.0-B2102005:
 
 - New features:
   - Added the ability to enable manual command line snippet. [#40](https://github.com/Azure/PSDocs.Azure/issues/40)
@@ -79,3 +88,4 @@ What's changed since pre-release v0.1.0-B2012006:
 
 [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
+[about_PSDocs_Azure_Conventions]: docs/concepts/en-US/about_PSDocs_Azure_Conventions.md

README.md

@@ -291,6 +291,8 @@ The following conceptual topics exist in the `PSDocs.Azure` module:
 - [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)
   - [AZURE_USE_COMMAND_LINE_SNIPPET](docs/concepts/en-US/about_PSDocs_Azure_Configuration.md#azure_use_command_line_snippet)
+- [Conventions](docs/concepts/en-US/about_PSDocs_Azure_Conventions.md)
+  - [Azure.NameByParentPath](docs/concepts/en-US/about_PSDocs_Azure_Conventions.md#azurenamebyparentpath)
 
 ## Changes and versioning
 

docs/concepts/en-US/about_PSDocs_Azure_Conventions.md

@@ -0,0 +1,44 @@
+# PSDocs_Azure_Conventions
+
+## about_PSDocs_Azure_Conventions
+
+## SHORT DESCRIPTION
+
+Describes how to use conventions included in `PSDocs.Azure`.
+
+## LONG DESCRIPTION
+
+PSDocs for Azure includes conventions that can be included when generating documentation.
+Conventions alter the default pipeline to customize it for a specific situation.
+
+When running `Invoke-PSDocument` add the `-Convention` parameter to specify one or more conventions.
+For example:
+
+```powershell
+Invoke-PSDocument -Convention 'Azure.NameByParentPath';
+```
+
+### Azure.NameByParentPath
+
+This convention can be used to change the default naming for documents.
+By default new documents are generated with the `README.md` file name.
+
+When the template file is stored under a well-known path `<name>/<version>/template.json` or `<name>/template.json`.
+i.e. `templates/storage/v1/template.json` or `templates/storage/template.json`
+
+The `name` and `version` can be used to name the output file.
+The resulting file name is updated to `<name>_<version>.md`.
+i.e. `storage_v1.md`
+
+For `version` to be detected, the version sub-directory must start with `v` and be followed by a number.
+When the version sub-directory a not detected the resulting file name is updated to `<name>.md`.
+i.e. `storage.md`
+
+## 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_Conventions.md.
+
+## KEYWORDS
+
+- Convention
+- NameByParentPath

pipeline.build.ps1

@@ -234,7 +234,7 @@ task BuildHelp BuildModule, PlatyPS, {
         &$pwshPath -Command {
             # Generate MAML and about topics
             Import-Module -Name PlatyPS -Verbose:$False;
-            $Null = New-ExternalHelp -OutputPath 'out/docs/PSDocs.Azure' -Path '.\docs\commands\en-US' -Force;
+            $Null = New-ExternalHelp -OutputPath 'out/docs/PSDocs.Azure' -Path '.\docs\commands\en-US', '.\docs\concepts\en-US' -Force;
         }
     }
 

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

@@ -0,0 +1,18 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+# Synopsis: Name documents by parent path.
+Export-PSDocumentConvention 'Azure.NameByParentPath' {
+    $template = Get-Item -Path $PSDocs.TargetObject;
+
+    # Get parent directory paths where <name>/v<version>/template.json
+    $version = $template.Directory.Name;
+    $name = $template.Directory.Parent.Name;
+
+    # Name the document <name>_<version>.md
+    $docName = $version;
+    if ($version -like 'v[0-9]*') {
+        $docName = [String]::Concat($name, '_', $version);
+    }
+    $PSDocs.Document.InstanceName = $docName;
+}

tests/PSDocs.Azure.Tests/Azure.Conventions.Tests.ps1

@@ -0,0 +1,53 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+#
+# Unit tests for PSDocs.Azure document conventions
+#
+
+[CmdletBinding()]
+param ()
+
+# Setup error handling
+$ErrorActionPreference = 'Stop';
+Set-StrictMode -Version latest;
+
+# Setup tests paths
+$rootPath = $PWD;
+$here = $PSScriptRoot;
+
+Import-Module (Join-Path -Path $rootPath -ChildPath out/modules/PSDocs.Azure) -Force;
+
+$outputPath = Join-Path -Path $rootPath -ChildPath out/tests/PSDocs.Azure.Tests/Conventions;
+Remove-Item -Path $outputPath -Force -Recurse -Confirm:$False -ErrorAction Ignore;
+$Null = New-Item -Path $outputPath -ItemType Directory -Force;
+
+Describe 'Conventions' -Tag 'Conventions' {
+    Context 'Azure.NameByParentPath' {
+        It 'Uses naming convention' {
+            $invokeParams = @{
+                Module = 'PSDocs.Azure'
+            }
+
+            # Generates templates
+            $templatePath = Join-Path -Path $rootPath -ChildPath 'templates/';
+            $result = Get-AzDocTemplateFile -Path $templatePath | ForEach-Object {
+                $template = Get-Item -Path $_.TemplateFile;
+                Invoke-PSDocument @invokeParams -OutputPath $outputPath -InputObject $template.FullName -Convention 'Azure.NameByParentPath'
+            }
+            $result | Should -Not -BeNullOrEmpty;
+            $result[0].Name | Should -BeLike 'storage_v1.md';
+            $result;
+
+            # Generates templates without version path
+            $templatePath = Join-Path -Path $here -ChildPath 'template-test/';
+            $result = Get-AzDocTemplateFile -Path $templatePath | ForEach-Object {
+                $template = Get-Item -Path $_.TemplateFile;
+                Invoke-PSDocument @invokeParams -OutputPath $outputPath -InputObject $template.FullName -Convention 'Azure.NameByParentPath'
+            }
+            $result | Should -Not -BeNullOrEmpty;
+            $result[0].Name | Should -BeLike 'template-test.md';
+            $result;
+        }
+    }
+}