Merge pull request #739 from FH-Inway/build-tools-action

👷 Add a GitHub action that executes the scripts of the building tools

.github/workflows/update-generated-text.yml

@@ -0,0 +1,47 @@
+# Run the scrips documented in https://github.com/d365collaborative/d365fo.tools/wiki/Building-tools
+# Creates a pull request with the changes
+
+name: d365fo.tools-Generate-Text
+
+on:
+  workflow_dispatch:
+
+jobs:
+
+  generateText:
+    name: Generate text
+    runs-on: windows-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Cache Powershell Modules
+      id: cache-powershell-modules
+      uses: actions/cache@v3
+      with:
+        path: C:\Users\runneradmin\Documents\WindowsPowerShell\Modules
+        key: 20210527|${{ hashFiles('**/vsts-prerequisites.ps1, **/buildtools.ps1') }}
+    - name: Prerequisites
+      if: steps.cache-powershell-modules.outputs.cache-hit != 'true'
+      shell: powershell
+      run: build\vsts-prerequisites.ps1
+    - name: BuildTools
+      if: steps.cache-powershell-modules.outputs.cache-hit != 'true'
+      shell: powershell
+      run: build\buildtools.ps1
+    - name: Format comment based help
+      shell: powershell
+      run: build\format-commentbasedhelp.ps1
+    - name: Generate parameter unit tests
+      shell: powershell
+      run: build\generate-parameterunittests.ps1
+    - name: Update documentation
+      shell: powershell
+      run: build\update-docs.ps1
+    - name: Create a pull request for changes
+      uses: peter-evans/create-pull-request@v5
+      with:
+        commit-message: | 
+          'Update comment based help and tests
+          
+          This pull request was automatically created by the d365fo.tools-Generate-Text action'
+        title: 'Update comment based help and tests'
+        body: 'This pull request was automatically created by the d365fo.tools-Generate-Text action'

build/buildtools.ps1

@@ -0,0 +1,19 @@
+# Installs the modules required for the automatic text generation.
+# See also https://github.com/d365collaborative/d365fo.tools/wiki/Building-tools
+
+Write-Host "Working on the machine named: $($env:computername)"
+Write-Host "The user running is: $($env:UserName)"
+
+$modules = @("PSModuleDevelopment", "platyPS")
+
+foreach ($item in $modules) {
+
+    $module = Get-InstalledModule -Name $item -ErrorAction SilentlyContinue
+
+    if ($null -eq $module) {
+        Write-Host "Installing $item" -ForegroundColor Cyan
+        Install-Module -Name $item -Force -Confirm:$false -Scope CurrentUser -AllowClobber -SkipPublisherCheck
+    }
+
+    Import-Module $item -Force
+}

build/format-commentbasedhelp.ps1

@@ -0,0 +1,54 @@
+# Script to format the comments/documentation of the cmdlets used for the commend based help.
+# based on https://gist.github.com/Splaxi/ff7485a24f6ed9937f3e8da76b5d4840
+# See also https://github.com/d365collaborative/d365fo.tools/wiki/Building-tools
+$path = "$PSScriptRoot\..\d365fo.tools"
+
+function Get-Header ($text) {
+    $start = $text.IndexOf('<#')
+    $temp = $start - 2
+    if($temp -gt 0) {
+        $text.SubString(0, $start - 2)
+    }
+    else {
+    ""
+    }
+}
+
+function Format-Help ($text) {
+    $start = $text.IndexOf('<#')
+    $end = $text.IndexOf('#>')
+    $help = $text.SubString($start + 2, $end - $start - 3)
+
+    $skipfirst = $null # to avoid trailing spaces
+    foreach ($newline in $help.Split("`n")) {
+        if (-not $skipfirst) { $skipfirst = $true; continue }
+        $trimmed = $newline.Trim()
+        foreach ($line in $trimmed) {
+            if ($line.StartsWith(".")) {
+                "    $line"
+            }
+            else {
+                "        $line"
+            }
+        }
+    }
+}
+
+function Get-Body ($text) {
+    $end = $text.IndexOf('#>')
+    $text.SubString($end, $text.Length - $end)
+}
+
+$files = New-Object System.Collections.ArrayList
+$filesPublic = Get-ChildItem -Path "$path\functions\*.ps1"
+$files.AddRange($filesPublic)
+$filesInternal = Get-ChildItem -Path "$path\internal\functions\*.ps1"
+$files.AddRange($filesInternal)
+
+foreach ($file in $files) {
+    $text = ($file | Get-Content -Raw).Trim()
+    Set-Content -Path $file.FullName -Encoding UTF8 -Value (Get-Header $text).TrimEnd()
+    Add-Content -Path $file.FullName -Encoding UTF8 -Value "<#".Trim()
+    Add-Content -Path $file.FullName -Encoding UTF8 -Value (Format-Help $text)
+    Add-Content -Path $file.FullName -Encoding UTF8 -Value (Get-Body $text).TrimEnd() -NoNewline
+}

build/generate-parameterunittests.ps1

@@ -0,0 +1,24 @@
+# Script to generate the parameter unit tests.
+# based on https://gist.github.com/Splaxi/2a24fc3c5193089ae7047ac5b8f104db
+# See also https://github.com/d365collaborative/d365fo.tools/wiki/Building-tools
+$path = "$PSScriptRoot\..\d365fo.tools"
+
+Import-Module $path -Force
+
+$excludeCommands = @()
+
+$commandsRaw = Get-Command -Module d365fo.tools -CommandType Function
+
+if ($excludeCommands.Count -gt 0) {
+    $commands = $commandsRaw | Select-String -Pattern $excludeCommands -SimpleMatch -NotMatch
+
+} else {
+    $commands = $commandsRaw
+}
+
+Remove-Item -Path "$path\tests\functions\*.Tests.ps1"
+foreach ( $commandName in $commands) {
+    Invoke-PSMDTemplate CommandTest -OutPath "$path\tests\functions" -Name $commandName -Force
+}
+
+Get-ChildItem -Path "$path\tests\functions" -Recurse -File | Set-PSMDEncoding

build/update-docs.ps1

@@ -0,0 +1,11 @@
+# Script to generate the comment based markdown help files.
+# based on https://gist.github.com/Splaxi/8934e13cb35918d13af6e3a21c208b0e
+# See also https://github.com/d365collaborative/d365fo.tools/wiki/Building-tools
+$path = "$PSScriptRoot\.."
+
+Import-Module "$path\d365fo.tools" -Force
+
+Remove-Item -Path "$path\docs\*.md"
+$null = New-MarkdownHelp -Module d365fo.tools -OutputFolder "$path\docs" -Force
+
+Get-ChildItem -Path "$path\docs" -Recurse -File | Set-PSMDEncoding