Adding Command Help Generation#37
Conversation
Minimum allowed line rate is |
There was a problem hiding this comment.
Pull request overview
This PR adds command help generation functionality to the PowerShell module build process using the updated Microsoft.PowerShell.PlatyPS module. The changes enable automatic generation of markdown-based help documentation from comment-based help in PowerShell functions, with the generated files being committed back to the repository during the build process.
Key changes include:
- Implemented a new
Export-CommandHelptask in the build script that generates markdown and MAML help files - Updated PlatyPS dependency from the legacy
platyPSpackage (v0.14.2) toMicrosoft.PowerShell.PlatyPS(v1.0.1) - Added GitHub Actions workflow steps to automatically generate and commit help documentation on main branch builds
Reviewed changes
Copilot reviewed 11 out of 12 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| src/Public/Get-PSScriptModuleInfo.ps1 | Added comprehensive comment-based help documentation including synopsis, description, parameters, examples, notes, and links |
| src/PSScriptModule.psd1 | Updated RootModule property from empty string to 'PSScriptModule.psm1' to properly define the module's root |
| requirements.psd1 | Updated PlatyPS package from legacy 'platyPS' v0.14.2 to new 'Microsoft.PowerShell.PlatyPS' v1.0.1 |
| docs/architecture.md | Removed architecture documentation file (deleted entirely) |
| build.ps1 | Removed build configuration file (deleted entirely) |
| PSScriptModule.build.ps1 | Major refactoring: renamed tasks with Invoke- prefix, added Export-CommandHelp task, reorganized build paths, and improved consistency in variable naming |
| .gitignore | Simplified gitignore rules to focus on build and test-results directories only |
| .github/workflows/ps-unit-tests.yml | Updated task reference from UnitTest to Invoke-UnitTests for consistency |
| .github/workflows/ps-static-code-analysis.yml | Updated task reference from PSScriptAnalyzer to Invoke-PSScriptAnalyzer for consistency |
| .github/workflows/ps-code-injection.yml | Updated task reference from InjectionHunter to Invoke-InjectionHunter for consistency |
| .github/workflows/ps-build-module.yml | Added Export-CommandHelp task execution, commit, and push steps to automatically update help files in the repository on main branch builds |
| .github/workflows/ci.yml | Added paths-ignore configuration to prevent CI runs when only help documentation files are updated |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| [void] (New-Item -Path $testOutputPath -ItemType Directory) | ||
| } | ||
| $Config = New-PesterConfiguration @{ | ||
| task Invoke-InjectionHunter { |
There was a problem hiding this comment.
The Invoke-InjectionHunter task is missing the code to create the test output directory before attempting to write test results. The Invoke-PSScriptAnalyzer task includes this check, but it was removed from Invoke-InjectionHunter. This could cause the task to fail if the test-results directory doesn't exist when Pester tries to write the output file.
| task Invoke-InjectionHunter { | |
| task Invoke-InjectionHunter { | |
| if (-not (Test-Path $testOutputPath)) { | |
| [void] (New-Item -Path $testOutputPath -ItemType Directory) | |
| } |
| [void] (New-Item -Path $testOutputPath -ItemType Directory) | ||
| } | ||
| # Synopsis: Run unit tests and generate code coverage report | ||
| task Invoke-UnitTests { |
There was a problem hiding this comment.
The Invoke-UnitTests task is missing the code to create the test output directory before attempting to write test results. This directory check was removed during refactoring but is necessary to prevent task failures when the test-results directory doesn't exist.
| task Invoke-UnitTests { | |
| task Invoke-UnitTests { | |
| if (-not (Test-Path $testOutputPath)) { | |
| [void] (New-Item -Path $testOutputPath -ItemType Directory) | |
| } |
| - name: Push help updates | ||
| run: | | ||
| git push origin HEAD:main |
There was a problem hiding this comment.
The "Push help updates" step is missing a conditional check. Currently it will attempt to push even if there were no changes to commit (when the "Commit generated help" step exits early). This step should have the same condition as the commit step or check if there are changes to push.
There was a problem hiding this comment.
@copilot open a new pull request to apply changes based on this feedback
| } | ||
|
|
||
| # Synopsis: Generate module help documentation | ||
| task Export-CommandHelp { |
There was a problem hiding this comment.
The Export-CommandHelp task depends on the Build task output but has no explicit dependency declaration. If this task is run independently, it will fail because the module at the path "out/$moduleName/$moduleName.psd1" won't exist. Consider adding Build as a task dependency.
| task Export-CommandHelp { | |
| task Export-CommandHelp -Depends Build { |
| $helpFiles = Measure-PlatyPSMarkdown -Path "$buildPath/help/PSScriptModule/*.md" | ||
| foreach ($helpFile in $helpFiles) { | ||
| [void] (Test-MarkdownCommandHelp -Path $helpFile.FilePath) | ||
| } | ||
|
|
||
| # Generate module help file | ||
| $mdfiles = Measure-PlatyPSMarkdown -Path "$buildPath/help/PSScriptModule/*.md" | Where-Object Filetype -Match 'CommandHelp' |
There was a problem hiding this comment.
The module name "PSScriptModule" is hardcoded in the path instead of using the $moduleName variable that is already defined in the Enter-Build block. This creates a maintainability issue if the module name changes. Consider using $moduleName consistently.
| $helpFiles = Measure-PlatyPSMarkdown -Path "$buildPath/help/PSScriptModule/*.md" | |
| foreach ($helpFile in $helpFiles) { | |
| [void] (Test-MarkdownCommandHelp -Path $helpFile.FilePath) | |
| } | |
| # Generate module help file | |
| $mdfiles = Measure-PlatyPSMarkdown -Path "$buildPath/help/PSScriptModule/*.md" | Where-Object Filetype -Match 'CommandHelp' | |
| $helpFiles = Measure-PlatyPSMarkdown -Path "$buildPath/help/$moduleName/*.md" | |
| foreach ($helpFile in $helpFiles) { | |
| [void] (Test-MarkdownCommandHelp -Path $helpFile.FilePath) | |
| } | |
| # Generate module help file | |
| $mdfiles = Measure-PlatyPSMarkdown -Path "$buildPath/help/$moduleName/*.md" | Where-Object Filetype -Match 'CommandHelp' |
| $helpFiles = Measure-PlatyPSMarkdown -Path "$buildPath/help/PSScriptModule/*.md" | ||
| foreach ($helpFile in $helpFiles) { | ||
| [void] (Test-MarkdownCommandHelp -Path $helpFile.FilePath) | ||
| } | ||
|
|
||
| # Generate module help file | ||
| $mdfiles = Measure-PlatyPSMarkdown -Path "$buildPath/help/PSScriptModule/*.md" | Where-Object Filetype -Match 'CommandHelp' |
There was a problem hiding this comment.
The module name "PSScriptModule" is hardcoded in the path instead of using the $moduleName variable. This creates a maintainability issue if the module name changes. Consider using $moduleName consistently.
| $helpFiles = Measure-PlatyPSMarkdown -Path "$buildPath/help/PSScriptModule/*.md" | |
| foreach ($helpFile in $helpFiles) { | |
| [void] (Test-MarkdownCommandHelp -Path $helpFile.FilePath) | |
| } | |
| # Generate module help file | |
| $mdfiles = Measure-PlatyPSMarkdown -Path "$buildPath/help/PSScriptModule/*.md" | Where-Object Filetype -Match 'CommandHelp' | |
| $helpFiles = Measure-PlatyPSMarkdown -Path "$buildPath/help/$moduleName/*.md" | |
| foreach ($helpFile in $helpFiles) { | |
| [void] (Test-MarkdownCommandHelp -Path $helpFile.FilePath) | |
| } | |
| # Generate module help file | |
| $mdfiles = Measure-PlatyPSMarkdown -Path "$buildPath/help/$moduleName/*.md" | Where-Object Filetype -Match 'CommandHelp' |
| paths-ignore: | ||
| - 'docs/help/**' |
There was a problem hiding this comment.
The paths-ignore configuration will prevent CI from running when help files are updated, but this creates a potential issue: if someone manually edits help files with errors, CI won't catch those issues. The workflow could trigger an infinite loop if help generation produces different output each time it runs (e.g., timestamps). Consider adding a condition to the commit/push steps to only run on release/tag events instead of ignoring these paths in CI.
| paths-ignore: | |
| - 'docs/help/**' |
|
@copilot open a new pull request to apply changes based on the comments in this thread |
No description provided.