From 8297eb1fe6c26f93451fca423e6f7bcb140bbbc4 Mon Sep 17 00:00:00 2001
From: Rain Sallow <rain@chocolatey.io>
Date: Thu, 3 Oct 2024 17:11:01 -0400
Subject: [PATCH] (maint) Update documentation generation script

When working on this, some irregularities were noted with the generation
of the documentation, so these changes avoid the issues that arose.
---
 update-cmdlet-documentation.ps1 | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/update-cmdlet-documentation.ps1 b/update-cmdlet-documentation.ps1
index b5d033bf8c..53813eaf5e 100644
--- a/update-cmdlet-documentation.ps1
+++ b/update-cmdlet-documentation.ps1
@@ -1,4 +1,6 @@
-<#
+# PowerShell Core generates additional documentation that may not be correct for running under Windows PowerShell.
+#Requires -PSEdition Desktop
+<#
 .SYNOPSIS
 Generates Markdown documentation for the Chocolatey.PowerShell portion of Chocolatey's installer module commands.
 
@@ -85,12 +87,12 @@ if (-not (Get-Module Chocolatey.PowerShell)) {
     throw "The Chocolatey.PowerShell module was not able to be loaded, exiting documentation generation."
 }
 
-$newOrUpdatedFiles = [System.Collections.Generic.HashSet[System.IO.FileSystemInfo]] @(
+$newOrUpdatedFiles = @(
     if ($NewCommand) {
-        New-MarkdownHelp -Command $NewCommand -OutputFolder "$PSScriptRoot\docs" -ExcludeDontShow
+        New-MarkdownHelp -Command $NewCommand -OutputFolder $documentationPath -ExcludeDontShow
     }
 
-    Update-MarkdownHelp -Path $documentationPath -ExcludeDontShow
+    Update-MarkdownHelp -Path $documentationPath -ExcludeDontShow | Where-Object BaseName -ne $NewCommand
 )
 
 $incompleteFiles = $newOrUpdatedFiles | Select-String '\{\{[^}]+}}' | Select-Object -ExpandProperty Path
@@ -116,7 +118,7 @@ $newOrUpdatedFiles = $newOrUpdatedFiles |
         
         $frontMatterBounds = 0
         $content = $content | ForEach-Object {
-            if ($_ -match '\[(?<name>[^\]]+)\]\(xref:(?<xref>[^#,]+)(#(?<anchor>[^,]+))?,(?<classes>[^)]+)\)') {
+            if ($_ -match '\[(?<name>[^\]]+)\]\(xref:(?<xref>[^#,]+)(#(?<anchor>[^,]+))?(?:,(?<classes>[^)]+))?\)') {
                 # replace any lines that are an xref link with the html/xml format that astro uses <Xref ... />
                 $xml = [xml]::new()
                 $node = $xml.CreateElement('Xref')
@@ -134,9 +136,11 @@ $newOrUpdatedFiles = $newOrUpdatedFiles |
                     $null = $node.Attributes.Append($anchor)
                 }
 
-                $classes = $xml.CreateAttribute('classes')
-                $classes.Value = $matches['classes']
-                $null = $node.Attributes.Append($classes)
+                if ($matches['classes']) {
+                    $classes = $xml.CreateAttribute('classes')
+                    $classes.Value = $matches['classes']
+                    $null = $node.Attributes.Append($classes)
+                }
 
                 $node.OuterXml
             }