Fix complex multiline examples, refactor test suite (#121) [release]

* Fix comments in code blocks being detected as markdown headers

* Initial version of Bootstrap.ps for integration tests

* Refactors Powershell7NativeMultiLineCode integration test

* Add generic path to bootstrap file

* Hardens SeperateHeaders

* Refactors CrossVersionCodeExamples integration test

* Refactors PlaceholderExamples integration test

* Test suite cleanup

* Fix PowerShell casing

* Fix PowerShell casing

* Fix complex code examples as used by Pester

* Add tests for SeparateMarkdownHeadings

* Rename empty line to blank line

* Move module .LINKS to README

Source/Private/IndentLineBelowOpeningBracket.ps1

@@ -0,0 +1,28 @@
+function IndentLineBelowOpeningBracket() {
+    <#
+        .SYNOPSIS
+            Indent line directly below line with opening curly bracket.
+
+        .NOTES
+            Because PlatyPS sometimes gets the indentation wrong with complex examples.
+
+        .LINK
+            https://regex101.com/r/eMCf3E/1
+    #>
+    param(
+        [Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile
+    )
+
+    GetCallerPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
+
+    Write-Verbose "Removing blank lines above closing curly bracket"
+
+    $content = ReadFile -MarkdownFile $MarkdownFile
+
+    $regex = [regex]::new('({\n)([^\s+].+)')
+
+    $content = $content -replace $regex, "`$1    `$2"
+
+    # replace file
+    WriteFile -MarkdownFile $MarkdownFile -Content $content
+}

Source/Private/IndentLineWithOpeningBracket.ps1

@@ -0,0 +1,50 @@
+function IndentLineWithOpeningBracket() {
+    <#
+        .SYNOPSIS
+            Corrects indentation for lines with opening curly brackets and incorrect indentation
+            by comparing indentation of the line below (and recalculating if things are amiss).
+
+        .NOTES
+            Skips correcting if the line below has 4-space indentation
+
+        .NOTES
+            The regex gives us three useful matching groups:
+            - Group 1 is the full first without the line feed
+            - Group 2 is the full second line without the line feed
+            - Group 3 contains the leading spaces of the second line
+
+        .LINK
+            https://regex101.com/r/mT2jLC/1
+    #>
+    param(
+        [Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile
+    )
+
+    GetCallerPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
+
+    Write-Verbose "Removing blank lines above closing curly bracket"
+
+    $content = ReadFile -MarkdownFile $MarkdownFile
+
+    $regex = [regex]::new('(?m)^([^\s].+{)\n((\s+)(.+))')
+
+    $callback = {
+        param($match)
+
+        # do nothing if next line starts with 4 spaces
+        if ($match.Groups[3].Value.Length -eq 4) {
+            return $match
+        }
+
+        # divide spacing of next line by 2 and use that as correct indentation
+        [string]$fixedIndentation = ""
+        $fixedIndentation.PadRight(($match.Groups[3].Value.Length / 2 - 1), " ")
+
+        $fixedIndentation + $match.Groups[1] + "`n" + $match.Groups[2]
+    }
+
+    $content = $regex.replace($content, $callback)
+
+    # replace file
+    WriteFile -MarkdownFile $MarkdownFile -Content $content
+}

Source/Private/NewSidebarIncludeFile.ps1

@@ -27,7 +27,7 @@ function NewSidebarIncludeFile() {
 /**
  * Import this file in your Docusaurus ``sidebars.js`` file.
  *
- * Auto-generated by Alt3.PowerShell.Docusaurus.
+ * Auto-generated by Alt3.Docusaurus.PowerShell.
  *
  * Copyright (c) 2019-present, ALT3 B.V.
  *

Source/Private/RemoveEmptyLinesAboveClosingBracket.ps1

@@ -0,0 +1,28 @@
+function RemoveEmptyLinesAboveClosingBracket() {
+    <#
+        .SYNOPSIS
+            Removes blank lines below lines ending with a closing curly bracket.
+
+        .NOTES
+            Required so following steps can trust formatting.
+
+        .LINK
+            https://regex101.com/r/xvEd2O/1
+    #>
+    param(
+        [Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile
+    )
+
+    GetCallerPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
+
+    Write-Verbose "Removing blank lines above closing curly bracket"
+
+    $content = ReadFile -MarkdownFile $MarkdownFile
+
+    $regex = [regex]::new('(\n\n+\s+}|\n\n})')
+
+    $content = $content -replace $regex, "`n}"
+
+    # replace file
+    WriteFile -MarkdownFile $MarkdownFile -Content $content
+}

Source/Private/RemoveEmptyLinesBelowOpeningBracket.ps1

@@ -0,0 +1,28 @@
+function RemoveEmptyLinesBelowOpeningBracket() {
+    <#
+        .SYNOPSIS
+            Removes blank lines below lines ending with an opening curly bracket.
+
+        .NOTES
+            Required so following steps can trust formatting.
+
+        .LINK
+            https://regex101.com/r/LlSt8t/1
+    #>
+    param(
+        [Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile
+    )
+
+    GetCallerPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
+
+    Write-Verbose "Removing blank lines below opening curly bracket"
+
+    $content = ReadFile -MarkdownFile $MarkdownFile
+
+    $regex = [regex]::new('({\n+\n)')
+
+    $content = $content -replace $regex, "{`n"
+
+    # replace file
+    WriteFile -MarkdownFile $MarkdownFile -Content $content
+}

Source/Private/ReplaceExamples.ps1

@@ -108,6 +108,7 @@ function ReplaceExamples() {
             Write-Verbose "=> $($header): Non-Adjacent Code Block (PowerShell 7)"
 
             $newExample = NewMarkdownExample -Header $header -Code $code -Description $description
+
             $newExamples += $newExample
             return
         }

Source/Private/SeparateHeaders.ps1 → Source/Private/SeparateMarkdownHeadings.ps1

@@ -1,29 +1,29 @@
-function SeparateHeaders() {
+function SeparateMarkdownHeadings() {
     <#
         .SYNOPSIS
-            Adds an empty line after markdown headers IF they are directly followed by an adjacent non-empty lines.
+            Adds a blank line after markdown headers IF they are directly followed by an adjacent non-blank lines.
 
         .NOTES
             This ensures the markdown format will match with e.g. Prettier which in turn will
             prevent getting format-change suggestions when running e.g. > Visual Studio Code
             > CTRL+SHIFT+P > Format Document.
 
         .LINK
-            https://regex101.com/r/Gsd3PX/1
+            https://regex101.com/r/llYF0H/1
     #>
     param(
         [Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile
     )
 
     GetCallerPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
 
-    Write-Verbose "Inserting empty line beneath non-separated headers."
+    Write-Verbose "Inserting blank line beneath non-separated headers."
 
     $content = ReadFile -MarkdownFile $MarkdownFile
 
-    $regex = [regex]::new('(?m)([#+].+)\n(.+)')
+    $regex = [regex]::new('(?m)^\n^([#]#{0,5}[a-z]*\s.+)\n(.+)')
 
-    $content = $content -replace $regex, ('$1' + "`n`n" + '$2')
+    $content = $content -replace $regex, "`n`$1`n`n`$2"
 
     # replace file
     WriteFile -MarkdownFile $MarkdownFile -Content $content

Source/Public/New-DocusaurusHelp.ps1

@@ -246,9 +246,16 @@ function New-DocusaurusHelp() {
             InsertUserMarkdown -MarkdownFile $mdxFile -Markdown $AppendMarkdown -Mode "Append"
         }
 
+        # Post-fix complex multiline code examples (https://github.com/pester/Pester/issues/2195)
+        RemoveEmptyLinesBelowOpeningBracket -MarkdownFile $mdxFile
+        RemoveEmptyLinesAboveClosingBracket -MarkdownFile $mdxFile
+        IndentLineBelowOpeningBracket -MarkdownFile $mdxFile
+        IndentLineWithOpeningBracket -MarkdownFile $mdxFile
+
+        ## Continue with general enrichment
         InsertPowerShellMonikers -MarkdownFile $mdxFile
         UnescapeSpecialChars -MarkdownFile $mdxFile
-        SeparateHeaders -MarkdownFile $mdxFile
+        SeparateMarkdownHeadings -MarkdownFile $mdxFile
         InsertFinalNewline -MarkdownFile $mdxFile
     }
 

Tests/Integration/Bootstrap.ps1

@@ -0,0 +1,29 @@
+<#
+    .SYNOPSIS
+    DRY helper for logic shared by all tests.
+
+    .NOTES
+    Every integration test follows the same logic:
+    - Imports the TestModule
+    - Uses the Alt-module to generate Docusaurus files in $env:Temp
+    - Makes sure the generated files exists
+    - Compares the generated mdx file to the expected mdx
+#>
+param(
+    [Parameter(Mandatory = $True)][System.IO.FileInfo]$TestFolder
+)
+
+$test = @{
+    Name       = $TestFolder.Directory.Name
+    Folder     = $TestFolder.Directory
+    Module     = Join-Path -Path $TestFolder.Directory -ChildPath "TestModule.psm1"
+    TempFolder = Join-Path -Path ([System.IO.Path]::GetTempPath()) -ChildPath $TestFolder.Directory.Name
+    MdxFile    = Join-Path -Path ([System.IO.Path]::GetTempPath()) -ChildPath $TestFolder.Directory.Name |
+    Join-Path -ChildPath "commands" |
+    Join-Path -ChildPath "Test-$($TestFolder.Directory.Name).mdx"
+}
+
+# unload the Test-Module
+if (Get-Module -Name "TestModule") {
+    Remove-Module -Name "TestModule" -Force -Verbose:$False
+}

Tests/Integration/CrossVersionCodeExamples.expected.mdx → Tests/Integration/CrossVersionCodeExamples/Expected.mdx

@@ -209,20 +209,16 @@ Once seen during development where rendering Pester Mock.mdx would lead to this
 
 ```powershell
 # This test-case is used to ensure that:
-
 # - using hash (#) characters does not break the EXAMPLES extraction regex
 # - hash characters get rendered as expected (in both code and description)
-
 # - regexes that change markdown-headers do not touch anything else
 
 ######################################
-
 ## Even when someone goes all ASCII ##
 ######################################
 
 function PublicFunction {
     # Has a lot of hash characters
-
 }
 
 Export-ModuleMember -Function PublicFunction # comment
@@ -237,7 +233,6 @@ Import-Module MyModule
 and is adjacent multi-line.
 
 ######################################################
-
 ## Another ASCII fan but now inside the description ##
 ######################################################
 
@@ -256,5 +251,3 @@ and is adjacent multi-line.
 ## NOTES
 
 ## RELATED LINKS
-
-[https://github.com/alt3/Docusaurus.PowerShell/issues/14#issuecomment-568552556](https://github.com/alt3/Docusaurus.PowerShell/issues/14#issuecomment-568552556)

Tests/Integration/CrossVersionCodeExamples/Integration.Tests.ps1

@@ -0,0 +1,42 @@
+BeforeDiscovery {
+    if (-not(Get-Module Alt3.Docusaurus.PowerShell)) {
+        throw "Required module 'Alt3.Docusaurus.Powershell' is not loaded."
+    }
+}
+
+BeforeAll {
+    . "$((Get-Item -Path $PSCommandPath).Directory.Parent)/Bootstrap.ps1" -TestFolder (Get-Item -Path $PSCommandPath)
+    Import-Module $test.Module -Force -DisableNameChecking -Verbose:$False -Scope Global
+
+    # generate and read Docusaurus files in $env:Temp
+    InModuleScope Alt3.Docusaurus.PowerShell -Parameters @{testModule = $test.Module; tempFolder = $test.TempFolder } {
+        New-DocusaurusHelp -Module $testModule -DocsFolder $tempFolder
+    }
+
+    $generatedMdx = Get-Content -Path $test.MdxFile
+    $expectedMdx = Get-Content (Join-Path -Path $test.Folder -ChildPath "Expected.mdx")
+}
+
+Describe "Integration Test to ensure all supported Code Example variants render identically on all PowerShell versions" {
+    It "Mdx file generated for test should exist" {
+        $test.MdxFile | Should -Exist
+    }
+
+    It "Mdx file generated for test should have content" {
+        $generatedMdx | Should -Not -BeNullOrEmpty
+    }
+
+    It "Mdx file generated for test should not contain CRLF" {
+        (Get-Content -Path $test.MdxFile -Raw) -match "`r`n" | Should -Be $False
+    }
+
+    It "Content of generated mdx file is identical to that of expected fixture" {
+        $generatedMdx | Should -BeExactly $expectedMdx
+    }
+}
+
+AfterAll {
+    if (Get-Module Alt3.Docusaurus.PowerShell) {
+        Remove-Item $test.TempFolder -Recurse -Force
+    }
+}

Tests/Integration/CrossVersionCodeExamples/README.md

@@ -0,0 +1,9 @@
+# CrossVersionCodeExamples
+
+This test assures:
+
+- That all `Get-Help` examples render identically on **all** PowerShell versions
+
+Additional information:
+
+- Logic described at https://github.com/alt3/Docusaurus.PowerShell/issues/14#issuecomment-568552556

Tests/Integration/CrossVersionCodeExamples.psm1 → Tests/Integration/CrossVersionCodeExamples/TestModule.psm1

@@ -3,9 +3,6 @@ function Test-CrossVersionCodeExamples {
     .SYNOPSIS
         Dummy module to ensure all supported Get-Help example variations render identically on all PowerShell versions.
 
-    .LINK
-        https://github.com/alt3/Docusaurus.PowerShell/issues/14#issuecomment-568552556
-
     .EXAMPLE
         $exampleType = 'Native single-line example without description'