Add initial test configurations, modules, and functions

Author: MariusStorhaug

.github/workflows/Action-Test.yml

@@ -8,25 +8,30 @@ on:
   schedule:
     - cron: '0 0 * * *'
 
+env:
+  GH_TOKEN: ${{ github.token }}
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
-permissions:
-  contents: read
-  pull-requests: read
+permissions: {}
 
 jobs:
-  ActionTestBasic:
-    name: Action-Test - [Basic]
+  ActionTestDefault:
+    name: Action-Test - [Default]
     runs-on: ubuntu-latest
     steps:
-      # Need to check out as part of the test, as its a local action
       - name: Checkout repo
         uses: actions/checkout@v4
 
+      - name: Initialize environment
+        uses: PSModule/Initialize-PSModule@main
+
       - name: Action-Test
         uses: ./
         with:
-          working-directory: ./tests
-          subject: PSModule
+          Name: PSModuleTest
+          Path: tests/src
+          ModulesOutputPath: tests/outputs/modules
+          DocsOutputPath: tests/outputs/docs

.github/workflows/Auto-Configure.yml

@@ -1,27 +1,79 @@
-name: '{{ NAME }}'
-description: '{{ DESCRIPTION }}'
+name: Build-PSModuleDocumentation (by PSModule)
+description: Build documentation for a PowerShell module.
 author: PSModule
 branding:
-  icon: upload-cloud
-  color: white
+  icon: package
+  color: gray-dark
 
 inputs:
-  working-directory:
-    description: The working directory where Terraform will be executed
+  Name:
+    description: Name of the module to process.
     required: false
-  subject:
-    description: The subject to greet
+  Path:
+    description: Path to the folder where the modules are located.
     required: false
-    default: World
+    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'
 
 runs:
   using: composite
   steps:
-    - name: '{{ NAME }}'
+    - name: Download module artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: ${{ inputs.ModuleArtifactName }}
+        path: ${{ inputs.ModulesOutputPath }}
+
+    - name: Run Build-PSModuleDocumentation
       uses: PSModule/GitHub-Script@v1
       env:
-        GITHUB_ACTION_INPUT_subject: ${{ inputs.subject }}
+        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: |
-          # '{{ NAME }}'
+          # 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

.github/workflows/Auto-Document.yml

@@ -0,0 +1,126 @@
+#Requires -Modules @{ ModuleName = 'GitHub'; ModuleVersion = '0.13.2' }
+#Requires -Modules @{ ModuleName = 'Utilities'; ModuleVersion = '0.3.0' }
+
+function Build-PSModuleDocumentation {
+    <#
+        .SYNOPSIS
+        Builds a module.
+
+        .DESCRIPTION
+        Builds a module.
+    #>
+    [CmdletBinding()]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSReviewUnusedParameter', '', Scope = 'Function',
+        Justification = 'LogGroup - Scoping affects the variables line of sight.'
+    )]
+    param(
+        # Name of the module.
+        [Parameter(Mandatory)]
+        [string] $ModuleName,
+
+        # Path to the folder where the modules are located.
+        [Parameter(Mandatory)]
+        [string] $ModuleSourceFolderPath,
+
+        # Path to the folder where the built modules are outputted.
+        [Parameter(Mandatory)]
+        [string] $ModulesOutputFolderPath,
+
+        # Path to the folder where the documentation is outputted.
+        [Parameter(Mandatory)]
+        [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]"
+
+        $docsOutputFolder = New-Item -Path $DocsOutputFolderPath -ItemType Directory -Force
+        Write-Host "Docs output folder:   [$docsOutputFolder]"
+    }
+
+
+    LogGroup 'Build docs - Generate markdown help' {
+        $ModuleName | Remove-Module -Force
+        Import-Module -Name $ModuleName -Force -RequiredVersion '999.0.0'
+        Write-Host ($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
+            $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
+            }
+            $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
+        }
+    }
+
+    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"
+
+            # 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
+        }
+    }
+
+    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 $_
+        }
+    }
+}

action.yml

@@ -1,24 +1,53 @@
-#Requires -Modules GitHub
+#Requires -Modules Utilities
 
 [CmdletBinding()]
-param(
-    [Parameter()]
-    [string] $Subject = $env:GITHUB_ACTION_INPUT_subject
-)
-
-begin {
-    $scriptName = $MyInvocation.MyCommand.Name
-    Write-Debug "[$scriptName] - Start"
+param()
+
+$path = (Join-Path -Path $PSScriptRoot -ChildPath 'helpers') | Get-Item | Resolve-Path -Relative
+LogGroup "Loading helper scripts from [$path]" {
+    Get-ChildItem -Path $path -Filter '*.ps1' -Recurse | Resolve-Path -Relative | ForEach-Object {
+        Write-Host "$_"
+        . $_
+    }
+}
+
+LogGroup 'Loading inputs' {
+    $moduleName = ($env:GITHUB_ACTION_INPUT_Name | IsNullOrEmpty) ? $env:GITHUB_REPOSITORY_NAME : $env:GITHUB_ACTION_INPUT_Name
+    Write-Host "Module name:         [$moduleName]"
+
+    $moduleSourceFolderPath = Join-Path -Path $env:GITHUB_WORKSPACE -ChildPath $env:GITHUB_ACTION_INPUT_Path/$moduleName
+    if (-not (Test-Path -Path $moduleSourceFolderPath)) {
+        $moduleSourceFolderPath = Join-Path -Path $env:GITHUB_WORKSPACE -ChildPath $env:GITHUB_ACTION_INPUT_Path
+    }
+    Write-Host "Source module path:  [$moduleSourceFolderPath]"
+    if (-not (Test-Path -Path $moduleSourceFolderPath)) {
+        throw "Module path [$moduleSourceFolderPath] does not exist."
+    }
+
+    $modulesOutputFolderPath = Join-Path $env:GITHUB_WORKSPACE $env:GITHUB_ACTION_INPUT_ModulesOutputPath
+    Write-Host "Modules output path: [$modulesOutputFolderPath]"
+    $docsOutputFolderPath = Join-Path $env:GITHUB_WORKSPACE $env:GITHUB_ACTION_INPUT_DocsOutputPath
+    Write-Host "Docs output path:    [$docsOutputFolderPath]"
 }
 
-process {
-    try {
-        Write-Output "Hello, $Subject!"
-    } catch {
-        throw $_
+LogGroup 'Build local scripts' {
+    Write-Host 'Execution order:'
+    $scripts = Get-ChildItem -Filter '*build.ps1' -Recurse | Sort-Object -Property Name | Resolve-Path -Relative
+    $scripts | ForEach-Object {
+        Write-Host " - $_"
+    }
+    $scripts | ForEach-Object {
+        LogGroup "Build local scripts - [$_]" {
+            . $_
+        }
     }
 }
 
-end {
-    Write-Debug "[$scriptName] - End"
+$params = @{
+    ModuleName              = $moduleName
+    ModuleSourceFolderPath  = $moduleSourceFolderPath
+    ModulesOutputFolderPath = $modulesOutputFolderPath
+    DocsOutputFolderPath    = $docsOutputFolderPath
 }
+
+Build-PSModuleDocumentation @params