PSModule · MariusStorhaug · Apr 18, 2025 · Feb 16, 2025 · Feb 16, 2025 · Feb 16, 2025
diff --git a/.github/workflows/Action-Test.yml b/.github/workflows/Action-Test.yml
@@ -25,21 +25,16 @@ jobs:
       - name: Checkout repo
         uses: actions/checkout@v4
 
-      - name: Initialize environment
-        uses: PSModule/Initialize-PSModule@main
-
       - name: Upload module artifact
         uses: actions/upload-artifact@v4
         with:
           name: module
-          path: tests/outputs/modules
+          path: tests/srcTestRepo/outputs/module
           if-no-files-found: error
           retention-days: 1
 
       - name: Action-Test
         uses: ./
         with:
           Name: PSModuleTest
-          Path: tests/src
-          ModulesOutputPath: tests/outputs/modules
-          DocsOutputPath: tests/outputs/docs
+          WorkingDirectory: tests/srcTestRepo
diff --git a/.github/workflows/Auto-Release.yml b/.github/workflows/Auto-Release.yml
@@ -30,5 +30,3 @@ jobs:
 
       - name: Auto-Release
         uses: PSModule/Auto-Release@v1
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
diff --git a/README.md b/README.md
@@ -1,17 +1,45 @@
-# Template-Action
+# Document-PSModule (by PSModule)
 
-A template repository for GitHub Actions
+A GitHub Action that automates the generation of documentation for PowerShell modules using Markdown help files.
+
+This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). It is recommended to use the
+[Process-PSModule workflow](https://github.com/PSModule/Process-PSModule) to automate the whole process of managing the PowerShell module.
+
+## Details
+
+This action:
+- Installs necessary modules, including `platyPS` for documentation generation.
+- Loads helper scripts required by the documentation process.
+- Generates Markdown documentation from PowerShell module files.
+- Ensures Markdown documentation is properly formatted, with correctly tagged PowerShell code blocks.
+- Adjusts Markdown file paths to mirror the structure of the source PowerShell module files.
+- Outputs organized Markdown documentation suitable for publishing or distribution.
 
 ## Usage
 
+Include this action in your workflow to automatically build and structure documentation for your PowerShell module.
+
 ### Inputs
 
+| Input              | Description                                   | Required | Default     |
+|--------------------|-----------------------------------------------|----------|-------------|
+| `Name`             | Name of the module to document.               | No       | <Repo name> |
+| `WorkingDirectory` | Directory from which the script will execute. | No       | `.`         |
+
 ### Secrets
 
+This action does not require any secrets.
+
 ### Outputs
 
+This action does not have defined outputs.
+
 ### Example
 
 ```yaml
-Example here
+- name: Document PowerShell Module
+  uses: PSModule/Document-PSModule@v1
+  with:
+    Name: 'MyModule'
+    WorkingDirectory: './module-directory'
 ```
diff --git a/action.yml b/action.yml
@@ -1,4 +1,4 @@
-name: Build-PSModuleDocumentation (by PSModule)
+name: Document-PSModule (by PSModule)
 description: Build documentation for a PowerShell module.
 author: PSModule
 branding:
@@ -9,71 +9,22 @@ inputs:
   Name:
     description: Name of the module to process.
     required: false
-  Path:
-    description: Path to the folder where the modules are located.
+  WorkingDirectory:
+    description: The working directory where the script will run from.
     required: false
-    default: src
-  ModulesOutputPath:
-    description: Path to the folder where the built modules are outputted.
-    required: false
-    default: outputs/modules
-  DocsOutputPath:
-    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
-  Debug:
-    description: Enable debug output.
-    required: false
-    default: 'false'
-  Verbose:
-    description: Enable verbose output.
-    required: false
-    default: 'false'
-  Version:
-    description: Specifies the version of the GitHub module to be installed. The value must be an exact version.
-    required: false
-  Prerelease:
-    description: Allow prerelease versions if available.
-    required: false
-    default: 'false'
+    default: '.'
 
 runs:
   using: composite
   steps:
-    - name: Download module artifact
-      uses: actions/download-artifact@v4
-      with:
-        name: ${{ inputs.ModuleArtifactName }}
-        path: ${{ inputs.ModulesOutputPath }}
+    - name: Install-PSModuleHelpers
+      uses: PSModule/Install-PSModuleHelpers@v1
 
-    - name: Run Build-PSModuleDocumentation
-      uses: PSModule/GitHub-Script@v1
+    - name: Document-PSModule
+      shell: pwsh
       env:
         GITHUB_ACTION_INPUT_Name: ${{ inputs.Name }}
-        GITHUB_ACTION_INPUT_Path: ${{ inputs.Path }}
-        GITHUB_ACTION_INPUT_ModulesOutputPath: ${{ inputs.ModulesOutputPath }}
-        GITHUB_ACTION_INPUT_DocsOutputPath: ${{ inputs.DocsOutputPath }}
-      with:
-        Debug: ${{ inputs.Debug }}
-        Prerelease: ${{ inputs.Prerelease }}
-        Verbose: ${{ inputs.Verbose }}
-        Version: ${{ inputs.Version }}
-        Script: |
-          # Build-PSModuleDocumentation
-          ${{ github.action_path }}\scripts\main.ps1
-
-    - name: Upload docs artifact
-      uses: actions/upload-artifact@v4
-      with:
-        name: ${{ inputs.DocsArtifactName }}
-        path: ${{ inputs.DocsOutputPath }}
-        if-no-files-found: error
-        retention-days: 1
+      working-directory: ${{ inputs.WorkingDirectory }}
+      run: |
+        # Build-PSModuleDocumentation
+        ${{ github.action_path }}/scripts/main.ps1
diff --git a/scripts/helpers/Build-PSModuleDocumentation.ps1 b/scripts/helpers/Build-PSModuleDocumentation.ps1
@@ -7,16 +7,10 @@
     Builds a module.
     #>
     [CmdletBinding()]
-    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
-        'PSReviewUnusedParameter', '', Scope = 'Function',
-        Justification = 'LogGroup - Scoping affects the variables line of sight.'
-    )]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSAvoidUsingWriteHost', '', Scope = 'Function',
         Justification = 'Want to just write to the console, not the pipeline.'
     )]
-    #Requires -Modules GitHub
-    #Requires -Modules Utilities
     param(
         # Name of the module.
         [Parameter(Mandatory)]
@@ -35,95 +29,99 @@
         [string] $DocsOutputFolderPath
     )
 
-    LogGroup "Documenting module [$ModuleName]" {
-        Write-Host "Source path:          [$ModuleSourceFolderPath]"
-        if (-not (Test-Path -Path $ModuleSourceFolderPath)) {
-            Write-Error "Source folder not found at [$ModuleSourceFolderPath]"
-            exit 1
-        }
-        $moduleSourceFolder = Get-Item -Path $ModuleSourceFolderPath
-        Write-Host "Module source folder: [$moduleSourceFolder]"
-
-        $moduleOutputFolder = New-Item -Path $ModulesOutputFolderPath -Name $ModuleName -ItemType Directory -Force
-        Write-Host "Module output folder: [$moduleOutputFolder]"
+    Write-Host "::group::Documenting module [$ModuleName]"
+    [pscustomobject]@{
+        ModuleName              = $ModuleName
+        ModuleSourceFolderPath  = $ModuleSourceFolderPath
+        ModulesOutputFolderPath = $ModulesOutputFolderPath
+        DocsOutputFolderPath    = $DocsOutputFolderPath
+    } | Format-List | Out-String
 
-        $docsOutputFolder = New-Item -Path $DocsOutputFolderPath -ItemType Directory -Force
-        Write-Host "Docs output folder:   [$docsOutputFolder]"
+    if (-not (Test-Path -Path $ModuleSourceFolderPath)) {
+        Write-Error "Source folder not found at [$ModuleSourceFolderPath]"
+        exit 1
     }
+    $moduleSourceFolder = Get-Item -Path $ModuleSourceFolderPath
+    $moduleOutputFolder = New-Item -Path $ModulesOutputFolderPath -Name $ModuleName -ItemType Directory -Force
+    $docsOutputFolder = New-Item -Path $DocsOutputFolderPath -ItemType Directory -Force
 
-    LogGroup 'Build docs - Generate markdown help' {
-        Add-PSModulePath -Path (Split-Path -Path $ModuleOutputFolder -Parent)
-        $ModuleName | Remove-Module -Force -ErrorAction SilentlyContinue
-        Import-PSModule -Path $ModuleOutputFolder -ModuleName $ModuleName
-        Write-Host ($ModuleName | Get-Module)
-        $null = New-MarkdownHelp -Module $ModuleName -OutputFolder $DocsOutputFolder -Force -Verbose
+    Write-Host '::group::Build docs - Generate markdown help - Raw'
+    Install-PSModule -Path $ModuleOutputFolder
+    Write-Host ($ModuleName | Get-Module)
+    $null = New-MarkdownHelp -Module $ModuleName -OutputFolder $DocsOutputFolder -Force -Verbose
+    Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
+        $fileName = $_.Name
+        Write-Host "::group:: - [$fileName]"
+        Show-FileContent -Path $_
     }
 
-    LogGroup 'Build docs - Fix markdown code blocks' {
-        Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
-            $content = Get-Content -Path $_.FullName
-            $fixedOpening = $false
-            $newContent = @()
-            foreach ($line in $content) {
-                if ($line -match '^```$' -and -not $fixedOpening) {
-                    $line = $line -replace '^```$', '```powershell'
-                    $fixedOpening = $true
-                } elseif ($line -match '^```.+$') {
-                    $fixedOpening = $true
-                } elseif ($line -match '^```$') {
-                    $fixedOpening = $false
-                }
-                $newContent += $line
+    Write-Host '::group::Build docs - Fix markdown code blocks'
+    Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
+        $content = Get-Content -Path $_.FullName
+        $fixedOpening = $false
+        $newContent = @()
+        foreach ($line in $content) {
+            if ($line -match '^```$' -and -not $fixedOpening) {
+                $line = $line -replace '^```$', '```powershell'
+                $fixedOpening = $true
+            } elseif ($line -match '^```.+$') {
+                $fixedOpening = $true
+            } elseif ($line -match '^```$') {
+                $fixedOpening = $false
             }
-            $newContent | Set-Content -Path $_.FullName
+            $newContent += $line
         }
+        $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 '\\`', '`'
-            $content = $content -replace '\\\[', '['
-            $content = $content -replace '\\\]', ']'
-            $content = $content -replace '\\\<', '<'
-            $content = $content -replace '\\\>', '>'
-            $content = $content -replace '\\\\', '\'
-            $content | Set-Content -Path $_.FullName
-        }
+    Write-Host '::group::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 '\\`', '`'
+        $content = $content -replace '\\\[', '['
+        $content = $content -replace '\\\]', ']'
+        $content = $content -replace '\\\<', '<'
+        $content = $content -replace '\\\>', '>'
+        $content = $content -replace '\\\\', '\'
+        $content | Set-Content -Path $_.FullName
     }
 
-    LogGroup 'Build docs - Structure markdown files to match source files' {
-        $PublicFunctionsFolder = Join-Path $ModuleSourceFolder.FullName 'functions\public' | Get-Item
-        Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
-            $file = $_
-            Write-Host "Processing:        $file"
+    Write-Host '::group::Build docs - Structure markdown files to match source files'
+    $PublicFunctionsFolder = Join-Path $ModuleSourceFolder.FullName 'functions\public' | Get-Item
+    Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
+        $file = $_
+        $relPath = [System.IO.Path]::GetRelativePath($DocsOutputFolder.FullName, $file.FullName)
+        Write-Host " - $relPath"
+        Write-Host "   Path:     $file"
 
-            # find the source code file that matches the markdown file
-            $scriptPath = Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force | Where-Object { $_.Name -eq ($file.BaseName + '.ps1') }
-            Write-Host "Found script path: $scriptPath"
-            $docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName).Replace('.ps1', '.md')
-            Write-Host "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 $PublicFunctionsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
-            $file = $_
-            Write-Host "Processing:        $file"
-            $docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName)
-            Write-Host "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
-        }
+        # find the source code file that matches the markdown file
+        $scriptPath = Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force | Where-Object { $_.Name -eq ($file.BaseName + '.ps1') }
+        Write-Host "   PS1 path: $scriptPath"
+        $docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName).Replace('.ps1', '.md')
+        Write-Host "   MD path:  $docsFilePath"
+        $docsFolderPath = Split-Path -Path $docsFilePath -Parent
+        $null = New-Item -Path $docsFolderPath -ItemType Directory -Force
+        Move-Item -Path $file.FullName -Destination $docsFilePath -Force
     }
 
+    Write-Host '::group::Build docs - Move markdown files from source files to docs'
+    Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
+        $file = $_
+        $relPath = [System.IO.Path]::GetRelativePath($PublicFunctionsFolder.FullName, $file.FullName)
+        Write-Host " - $relPath"
+        Write-Host "   Path:     $file"
+
+        $docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName)
+        Write-Host "   MD path:  $docsFilePath"
+        $docsFolderPath = Split-Path -Path $docsFilePath -Parent
+        $null = New-Item -Path $docsFolderPath -ItemType Directory -Force
+        Move-Item -Path $file.FullName -Destination $docsFilePath -Force
+    }
+
+    Write-Host '────────────────────────────────────────────────────────────────────────────────'
     Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
         $fileName = $_.Name
-        $hash = (Get-FileHash -Path $_.FullName -Algorithm SHA256).Hash
-        LogGroup " - [$fileName] - [$hash]" {
-            Show-FileContent -Path $_
-        }
+        Write-Host "::group:: - [$fileName]"
+        Show-FileContent -Path $_
     }
 }