🚀 [Feature]: Structure docs similar to the source code

.github/workflows/Action-Test.yml

@@ -34,7 +34,7 @@ jobs:
 
   ActionTestWithManifest:
     name: Action-Test - [DefaultWithManifest]
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - name: Checkout repo
         uses: actions/checkout@v4
@@ -49,3 +49,5 @@ jobs:
           Path: tests/srcWithManifest
           ModulesOutputPath: tests/outputs/modules
           DocsOutputPath: tests/outputs/docs
+          ModuleArtifactName: moduleWithManifest
+          DocsArtifactName: docsWithManifest

README.md

@@ -30,6 +30,8 @@ During the build process the following steps are performed:
 | `Path` | Path to the folder where the modules are located. | `false` | `src` |
 | `ModulesOutputPath` | Path to the folder where the built modules are outputted. | `false` | `outputs/modules` |
 | `DocsOutputPath` | Path to the folder where the built docs are outputted. | `false` | `outputs/docs` |
+| `ModuleArtifactName` | Name of the module artifact to upload. | `false` | `module` |
+| `DocsArtifactName` | Name of the docs artifact to upload. | `false` | `docs` |
 
 ## Root module
 

action.yml

@@ -21,6 +21,14 @@ inputs:
     description: Path to the folder where the built docs are outputted.
     required: false
     default: outputs/docs
+  ModuleArtifactName:
+    description: Name of the module artifact to upload.
+    required: false
+    default: module
+  DocsArtifactName:
+    description: Name of the docs artifact to upload.
+    required: false
+    default: docs
 
 runs:
   using: composite
@@ -36,3 +44,19 @@ runs:
         Script: |
           # Build-PSModule
           . "${{ github.action_path }}\scripts\main.ps1" -Verbose
+
+    - name: Upload module artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ inputs.ModuleArtifactName }}
+        path: ${{ inputs.ModulesOutputPath }}
+        if-no-files-found: error
+        retention-days: 1
+
+    - name: Upload docs artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ inputs.DocsArtifactName }}
+        path: ${{ inputs.DocsOutputPath }}
+        if-no-files-found: error
+        retention-days: 1

scripts/helpers/Build-PSModule.ps1

@@ -51,7 +51,7 @@ function Build-PSModule {
     Build-PSModuleManifest -ModuleName $ModuleName -ModuleOutputFolder $moduleOutputFolder
     Build-PSModuleRootModule -ModuleName $ModuleName -ModuleOutputFolder $moduleOutputFolder
     Update-PSModuleManifestAliasesToExport -ModuleName $ModuleName -ModuleOutputFolder $moduleOutputFolder
-    Build-PSModuleDocumentation -ModuleName $ModuleName -DocsOutputFolder $docsOutputFolder
+    Build-PSModuleDocumentation -ModuleName $ModuleName -ModuleSourceFolder $moduleSourceFolder -DocsOutputFolder $docsOutputFolder
 
     LogGroup 'Build manifest file - Final Result' {
         $outputManifestPath = Join-Path -Path $ModuleOutputFolder -ChildPath "$ModuleName.psd1"

scripts/helpers/Build/Build-PSModuleDocumentation.ps1

@@ -22,6 +22,10 @@ function Build-PSModuleDocumentation {
         [Parameter(Mandatory)]
         [string] $ModuleName,
 
+        # Path to the folder where the module source code is located.
+        [Parameter(Mandatory)]
+        [System.IO.DirectoryInfo] $ModuleSourceFolder,
+
         # Folder where the documentation for the modules should be outputted. 'outputs/docs/MyModule'
         [Parameter(Mandatory)]
         [System.IO.DirectoryInfo] $DocsOutputFolder
@@ -32,6 +36,9 @@ function Build-PSModuleDocumentation {
         Import-Module -Name $ModuleName -Force -RequiredVersion '999.0.0'
         Write-Verbose ($ModuleName | Get-Module)
         $null = New-MarkdownHelp -Module $ModuleName -OutputFolder $DocsOutputFolder -Force -Verbose
+    }
+
+    LogGroup 'Build docs - Fix markdown code blocks' {
         Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
             $content = Get-Content -Path $_.FullName
             $fixedOpening = $false
@@ -49,6 +56,9 @@ function Build-PSModuleDocumentation {
             }
             $newContent | Set-Content -Path $_.FullName
         }
+    }
+
+    LogGroup 'Build docs - Fix markdown escape characters' {
         Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
             $content = Get-Content -Path $_.FullName -Raw
             $content = $content -replace '\\`', '`'
@@ -61,6 +71,36 @@ function Build-PSModuleDocumentation {
         }
     }
 
+    # Markdown files are called the same as the source files, but with a .md extension.
+    # They are all located flat in the docsoutputfolder.
+    # I want the markdown files to be moved in the same folder structure as the source files.
+    LogGroup 'Build docs - Structure markdown files to match source files' {
+        $PublicFunctions = Join-Path $ModuleSourceFolder.FullName 'functions\public' | Get-Item
+        Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
+            $file = $_
+            Write-Verbose "Processing:        $file"
+
+            # find the source code file that matches the markdown file
+            $scriptPath = Get-ChildItem -Path $PublicFunctions -Recurse -Force | Where-Object { $_.Name -eq ($file.BaseName + '.ps1') }
+            Write-Verbose "Found script path: $scriptPath"
+            $docsFilePath = ($scriptPath.FullName).Replace($PublicFunctions.FullName, $DocsOutputFolder.FullName).Replace('.ps1', '.md')
+            Write-Verbose "Doc file path:     $docsFilePath"
+            $docsFolderPath = Split-Path -Path $docsFilePath -Parent
+            New-Item -Path $docsFolderPath -ItemType Directory -Force
+            Move-Item -Path $file.FullName -Destination $docsFilePath -Force
+        }
+        # Get the MD files that are in the public functions folder and move them to the same place in the docs folder
+        Get-ChildItem -Path $PublicFunctions -Recurse -Force -Include '*.md' | ForEach-Object {
+            $file = $_
+            Write-Verbose "Processing:        $file"
+            $docsFilePath = ($file.FullName).Replace($PublicFunctions.FullName, $DocsOutputFolder.FullName)
+            Write-Verbose "Doc file path:     $docsFilePath"
+            $docsFolderPath = Split-Path -Path $docsFilePath -Parent
+            New-Item -Path $docsFolderPath -ItemType Directory -Force
+            Move-Item -Path $file.FullName -Destination $docsFilePath -Force
+        }
+    }
+
     Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
         $fileName = $_.Name
         $hash = (Get-FileHash -Path $_.FullName -Algorithm SHA256).Hash

tests/src/functions/public/PSModule/PSModule.md

@@ -0,0 +1 @@
+# This is PSModule

tests/src/functions/public/SomethingElse/SomethingElse.md

@@ -0,0 +1 @@
+# This is SomethingElse

tests/srcWithManifest/functions/public/Get-PSModuleTest.ps1 → tests/srcWithManifest/functions/public/PSModule/Get-PSModuleTest.ps1

@@ -1,5 +1,5 @@
 #Requires -Modules Utilities
-#Requires -Modules @{ ModuleName = 'PSSemVer'; ModuleVersion = '1.0.0' }
+#Requires -Modules @{ ModuleName = 'PSSemVer'; RequiredVersion = '1.0.0' }
 #Requires -Modules @{ ModuleName = 'DynamicParams'; ModuleVersion = '1.1.8' }
 #Requires -Modules @{ ModuleName = 'Store'; ModuleVersion = '0.3.1' }
 

tests/srcWithManifest/functions/public/New-PSModuleTest.ps1 → tests/srcWithManifest/functions/public/PSModule/New-PSModuleTest.ps1

@@ -19,6 +19,8 @@ function New-PSModuleTest {
         'PSUseShouldProcessForStateChangingFunctions', '', Scope = 'Function',
         Justification = 'Reason for suppressing'
     )]
+    [Alias('New-PSModuleTestAlias1')]
+    [Alias('New-PSModuleTestAlias2')]
     [CmdletBinding()]
     param (
         # Name of the person to greet.
@@ -27,3 +29,9 @@ function New-PSModuleTest {
     )
     Write-Output "Hello, $Name!"
 }
+
+New-Alias New-PSModuleTestAlias3 New-PSModuleTest
+New-Alias -Name New-PSModuleTestAlias4 -Value New-PSModuleTest
+
+
+Set-Alias New-PSModuleTestAlias5 New-PSModuleTest

tests/srcWithManifest/functions/public/PSModule/PSModule.md

@@ -0,0 +1 @@
+# This is PSModule

tests/srcWithManifest/functions/public/SomethingElse/SomethingElse.md

@@ -0,0 +1 @@
+# This is SomethingElse