- Allow specification of markdown files to process with New-DocusaurusHelp. (#201) [release]

* - Allow specification of markdown files to process with `New-DocusaurusHelp`.

* - Rework new `New-DocusaurusHelp` parameter `-MarkdownCachePath` to `-PlatyPSMarkdownPath`.

As requested, place it into a separate parameter set and munge out the module's name from the supplied files.

* - Don't use the caller's relative path within `build-module.ps1`.

* - Ensure that `New-DocusaurusHelp`'s `-PlatyPSMarkdownPath` parameter is mandatory within its parameter set.

Co-authored-by: Frode Flaten <[email protected]>

* - Rework module name ascertaining for `-PlatyPSMarkdownPath` code.

* - Rate-limit the module name ascertaining for `-PlatyPSMarkdownPath` code to the first 10 files.

* - Properly guard off the module importing code when `-PlatyPSMarkdownPath` is used.

* - Rework "- Rate-limit the module name ascertaining for `-PlatyPSMarkdownPath` code to the first 10 files." to the correct intention of the reviewer.

* - Revert an aspect of the module import code in `New-DocusaurusHelp` to be 1:1 before I started so Pester doesn't have a sad.

* - Update documents export for website.

---------

Co-authored-by: Frode Flaten <[email protected]>

Author: mjr4077au

Source/Public/New-DocusaurusHelp.ps1

@@ -49,6 +49,11 @@ function New-DocusaurusHelp() {
 
             You may specify a module name, a `.psd1` file or a `.psm1` file.
 
+        .PARAMETER PlatyPSMarkdownPath
+            Specifies a path containing already prepared PlatyPS markdown files for processing.
+
+            If not provided, this function will generate the necessary files as required.
+
         .PARAMETER DocsFolder
             Specifies the absolute or relative **path** to the Docusaurus `docs` folder.
 
@@ -148,7 +153,10 @@ function New-DocusaurusHelp() {
     #>
     [cmdletbinding()]
     param(
-        [Parameter(Mandatory = $True)][string]$Module,
+        [Parameter(Mandatory = $True, ParameterSetName = 'Module')][string]$Module,
+        [Parameter(Mandatory = $True, ParameterSetName = 'PlatyPSMarkdownPath')]
+        [ValidateScript({ [System.IO.Directory]::Exists($_) })]
+        [string]$PlatyPSMarkdownPath,
         [Parameter(Mandatory = $False)][string]$DocsFolder = "docusaurus/docs",
         [Parameter(Mandatory = $False)][string]$Sidebar = "commands",
         [Parameter(Mandatory = $False)][array]$Exclude = @(),
@@ -167,18 +175,57 @@ function New-DocusaurusHelp() {
 
     GetCallerPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
 
-    # make sure the passed module is valid
-    if (Test-Path($Module)) {
-        Import-Module $Module -Force -Global
-        $Module = [System.IO.Path]::GetFileNameWithoutExtension($Module)
-    }
+    # Get the module's name fromn the supplied markdown files.
+    if ($PSCmdlet.ParameterSetName.Equals('PlatyPSMarkdownPath'))
+    {
+        # Get the module's name from the supplied markdown files.
+        $moduleName = Get-ChildItem -LiteralPath $PlatyPSMarkdownPath -Filter *.md |
+            Get-Content -ReadCount 10 -TotalCount 10 |
+            ForEach-Object { $_ -match '^Module Name: ' -replace '^Module Name:\s+' } |
+            Select-Object -Unique
+
+        # Throw if null or we've got more than one item.
+        if ($null -eq $moduleName)
+        {
+            $errSentence1 = 'Unable to determine the module name from the supplied markdown files.'
+            $errSentence2 = 'Please confirm their validity and try again.'
+            $PSCmdlet.ThrowTerminatingError([System.Management.Automation.ErrorRecord]::new(
+                    [System.ArgumentException]::new("$errSentence1 $errSentence2", 'PlatyPSMarkdownPath'),
+                    'ModuleNameIndeterminateError',
+                    [System.Management.Automation.ErrorCategory]::InvalidResult,
+                    $moduleName
+                ))
+        }
+        elseif ($moduleName -isnot [System.String])
+        {
+            $errSentence1 = "More than one module name was found within the supplied markdown files ('$([System.String]::Join("', '", $moduleName))')."
+            $errSentence2 = 'Please supply unique markdown files for a single module and try again.'
+            $PSCmdlet.ThrowTerminatingError([System.Management.Automation.ErrorRecord]::new(
+                    [System.ArgumentException]::new("$errSentence1 $errSentence2", 'PlatyPSMarkdownPath'),
+                    'DuplicateModuleNameError',
+                    [System.Management.Automation.ErrorCategory]::InvalidResult,
+                    $moduleName
+                ))
+        }
 
-    if (-Not(Get-Module -Name $Module)) {
-        $Module = $Module
-        throw "New-DocusaurusHelp: Specified module '$Module' is not loaded"
+        # Trim off the leading characters before continuing.
+        $Module = $moduleName
     }
+    else
+    {
+        # make sure the passed module is valid
+        if (Test-Path($Module)) {
+            Import-Module $Module -Force -Global
+            $Module = [System.IO.Path]::GetFileNameWithoutExtension($Module)
+        }
 
-    $moduleName = [io.path]::GetFileName($module)
+        if (-Not(Get-Module -Name $Module)) {
+            $Module = $Module
+            throw "New-DocusaurusHelp: Specified module '$Module' is not loaded"
+        }
+
+        $moduleName = [io.path]::GetFileName($module)
+    }
 
     # get version of this module so we can e.g. add version tag to generated files
     $alt3Version = Split-Path -Leaf $MyInvocation.MyCommand.ScriptBlock.Module.ModuleBase
@@ -194,8 +241,16 @@ function New-DocusaurusHelp() {
     InitializeTempFolder -Path $tempFolder
 
     # generate PlatyPs markdown files
-    Write-Verbose "Generating PlatyPS files."
-    New-MarkdownHelp -Module $Module -OutputFolder $tempFolder -Force | Out-Null
+    if ($PSCmdlet.ParameterSetName.Equals('Module'))
+    {
+        Write-Verbose "Generating PlatyPS files."
+        New-MarkdownHelp -Module $Module -OutputFolder $tempFolder -Force | Out-Null
+    }
+    else
+    {
+        Write-Verbose "Copying cached markdown files to temp folder."
+        Copy-Item -Path $PlatyPSMarkdownPath\*.md -Destination $tempFolder -Force -Confirm:$false
+    }
 
     # remove files matching excluded commands
     Write-Verbose "Removing excluded files:"

build-module.ps1

@@ -47,13 +47,13 @@ param(
 
 # Build new Alt3 module
 Write-Output "Building new module"
-Build-Module -SourcePath .\Source -VersionedOutputDirectory
+Build-Module -SourcePath $PSScriptRoot\Source -VersionedOutputDirectory
 
 # Prevent duplicate module versions breaking PlatyPS
 Remove-Module Alt3.Docusaurus.Powershell -Force -ErrorAction SilentlyContinue
 
 # Determine latest module version
-$outputFolder = ".\Output\Alt3.Docusaurus.Powershell"
+$outputFolder = "$PSScriptRoot\Output\Alt3.Docusaurus.Powershell"
 $latestModuleVersion = (Get-ChildItem -Path $outputFolder -Directory | Sort-Object CreationTime | Select-Object -Last 1).Name
 Write-Output "Importing newly built module $latestModuleVersion"
 

website/docs/commands/New-DocusaurusHelp.mdx

@@ -21,11 +21,22 @@ Generates Get-Help documentation in Docusaurus compatible `.mdx` format.
 
 ## SYNTAX
 
+### Module
+
+```powershell
+New-DocusaurusHelp -Module <String> [-DocsFolder <String>] [-Sidebar <String>] [-Exclude <Array>]
+ [-EditUrl <String>] [-MetaDescription <String>] [-MetaKeywords <Array>] [-PrependMarkdown <String>]
+ [-AppendMarkdown <String>] [-KeepHeader1] [-HideTitle] [-HideTableOfContents] [-NoPlaceHolderExamples]
+ [-Monolithic] [-VendorAgnostic] [<CommonParameters>]
+```
+
+### PlatyPSMarkdownPath
+
 ```powershell
-New-DocusaurusHelp [-Module] <String> [[-DocsFolder] <String>] [[-Sidebar] <String>] [[-Exclude] <Array>]
- [[-EditUrl] <String>] [[-MetaDescription] <String>] [[-MetaKeywords] <Array>] [[-PrependMarkdown] <String>]
- [[-AppendMarkdown] <String>] [-KeepHeader1] [-HideTitle] [-HideTableOfContents] [-NoPlaceHolderExamples]
- [-Monolithic] [-VendorAgnostic] [-ProgressAction <ActionPreference>] [<CommonParameters>]
+New-DocusaurusHelp -PlatyPSMarkdownPath <String> [-DocsFolder <String>] [-Sidebar <String>] [-Exclude <Array>]
+ [-EditUrl <String>] [-MetaDescription <String>] [-MetaKeywords <Array>] [-PrependMarkdown <String>]
+ [-AppendMarkdown <String>] [-KeepHeader1] [-HideTitle] [-HideTableOfContents] [-NoPlaceHolderExamples]
+ [-Monolithic] [-VendorAgnostic] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -83,11 +94,29 @@ You may specify a module name, a `.psd1` file or a `.psm1` file.
 
 ```yaml
 Type: String
-Parameter Sets: (All)
+Parameter Sets: Module
 Aliases:
 
 Required: True
-Position: 1
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -PlatyPSMarkdownPath
+
+Specifies a path containing already prepared PlatyPS markdown files for processing.
+
+If not provided, this function will generate the necessary files as required.
+
+```yaml
+Type: String
+Parameter Sets: PlatyPSMarkdownPath
+Aliases:
+
+Required: True
+Position: Named
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
@@ -105,7 +134,7 @@ Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 2
+Position: Named
 Default value: Docusaurus/docs
 Accept pipeline input: False
 Accept wildcard characters: False
@@ -123,7 +152,7 @@ Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 3
+Position: Named
 Default value: Commands
 Accept pipeline input: False
 Accept wildcard characters: False
@@ -139,7 +168,7 @@ Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 4
+Position: Named
 Default value: @()
 Accept pipeline input: False
 Accept wildcard characters: False
@@ -157,7 +186,7 @@ Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 5
+Position: Named
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
@@ -175,7 +204,7 @@ Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 6
+Position: Named
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
@@ -191,7 +220,7 @@ Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 7
+Position: Named
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
@@ -209,7 +238,7 @@ Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 8
+Position: Named
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
@@ -227,7 +256,7 @@ Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 9
+Position: Named
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
@@ -352,22 +381,6 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -ProgressAction
-
-\{\{ Fill ProgressAction Description \}\}
-
-```yaml
-Type: ActionPreference
-Parameter Sets: (All)
-Aliases: proga
-
-Required: False
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
@@ -399,4 +412,4 @@ $tempFolder = Get-Item (Join-Path -Path ([System.IO.Path]::GetTempPath()) -Child
 
 ## ADDITIONAL INFORMATION
 
-This page was auto-generated using the comment based help in Alt3.Docusaurus.Powershell 1.0.35.
+This page was auto-generated using the comment based help in Alt3.Docusaurus.Powershell 1.0.36.

website/docs/commands/docusaurus.sidebar.js

@@ -1,7 +1,7 @@
 /**
  * Import this file in your Docusaurus `sidebars.js` file.
  *
- * Auto-generated by Alt3.Docusaurus.Powershell 1.0.35.
+ * Auto-generated by Alt3.Docusaurus.Powershell 1.0.36.
  *
  * Copyright (c) 2019-present, ALT3 B.V.
  *