Skip to content

Commit ee78db8

Browse files
joshooajHeyItsGilbert
joshooaj
authored and
HeyItsGilbert
committed
feat: Add support for additional PlatyPS MarkdownHelp parameters (#77)
* Add `AlphabeticParamsOrder`, `ExcludeDontShow`, and `UseFullTypeName` options to `$PSBPreference.Docs` with default value of `$false` in `build.properties.ps1` * Add the same three parameters to `Build-PSBuildMarkdown` * Pass the same three parameters to `Build-PSBuildMarkdown` from `IB.tasks.ps1` and `psakeFile.ps1` * Add the same three parameters to the list of configurable options in the readme file
1 parent 791a9f6 commit ee78db8

File tree

5 files changed

+62
-17
lines changed

5 files changed

+62
-17
lines changed

‎PowerShellBuild/IB.tasks.ps1‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -117,11 +117,14 @@ $genMarkdownPreReqs = {
117117
# Synopsis: Generates PlatyPS markdown files from module help
118118
task GenerateMarkdown -if (. $genMarkdownPreReqs) StageFiles,{
119119
$buildMDParams = @{
120-
ModulePath = $PSBPreference.Build.ModuleOutDir
121-
ModuleName = $PSBPreference.General.ModuleName
122-
DocsPath = $PSBPreference.Docs.RootDir
123-
Locale = $PSBPreference.Help.DefaultLocale
124-
Overwrite = $PSBPreference.Docs.Overwrite
120+
ModulePath = $PSBPreference.Build.ModuleOutDir
121+
ModuleName = $PSBPreference.General.ModuleName
122+
DocsPath = $PSBPreference.Docs.RootDir
123+
Locale = $PSBPreference.Help.DefaultLocale
124+
Overwrite = $PSBPreference.Docs.Overwrite
125+
AlphabeticParamsOrder = $PSBPreference.Docs.AlphabeticParamsOrder
126+
ExcludeDontShow = $PSBPreference.Docs.ExcludeDontShow
127+
UseFullTypeName = $PSBPreference.Docs.UseFullTypeName
125128
}
126129
Build-PSBuildMarkdown @buildMDParams
127130
}

‎PowerShellBuild/Public/Build-PSBuildMarkdown.ps1‎

Lines changed: 31 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,12 @@ function Build-PSBuildMarkdown {
1414
The locale to save the markdown docs.
1515
.PARAMETER Overwrite
1616
Overwrite existing markdown files and use comment based help as the source of truth.
17+
.PARAMETER AlphabeticParamsOrder
18+
Order parameters alphabetically by name in PARAMETERS section. There are 5 exceptions: -Confirm, -WhatIf, -IncludeTotalCount, -Skip, and -First parameters will be the last.
19+
.PARAMETER ExcludeDontShow
20+
Exclude the parameters marked with `DontShow` in the parameter attribute from the help content.
21+
.PARAMETER UseFullTypeName
22+
Indicates that the target document will use a full type name instead of a short name for parameters.
1723
.EXAMPLE
1824
PS> Build-PSBuildMarkdown -ModulePath ./output/MyModule/0.1.0 -ModuleName MyModule -DocsPath ./docs -Locale en-US
1925
@@ -34,7 +40,16 @@ function Build-PSBuildMarkdown {
3440
[string]$Locale,
3541

3642
[parameter(Mandatory)]
37-
[bool]$Overwrite
43+
[bool]$Overwrite,
44+
45+
[parameter(Mandatory)]
46+
[bool]$AlphabeticParamsOrder,
47+
48+
[parameter(Mandatory)]
49+
[bool]$ExcludeDontShow,
50+
51+
[parameter(Mandatory)]
52+
[bool]$UseFullTypeName
3853
)
3954

4055
$moduleInfo = Import-Module "$ModulePath/$ModuleName.psd1" -Global -Force -PassThru
@@ -50,18 +65,27 @@ function Build-PSBuildMarkdown {
5065
}
5166

5267
if (Get-ChildItem -LiteralPath $DocsPath -Filter *.md -Recurse) {
68+
$updateMDParams = @{
69+
AlphabeticParamsOrder = $AlphabeticParamsOrder
70+
ExcludeDontShow = $ExcludeDontShow
71+
UseFullTypeName = $UseFullTypeName
72+
Verbose = $VerbosePreference
73+
}
5374
Get-ChildItem -LiteralPath $DocsPath -Directory | ForEach-Object {
54-
Update-MarkdownHelp -Path $_.FullName -Verbose:$VerbosePreference > $null
75+
Update-MarkdownHelp -Path $_.FullName @updateMDParams > $null
5576
}
5677
}
5778

5879
# ErrorAction set to SilentlyContinue so this command will not overwrite an existing MD file.
5980
$newMDParams = @{
60-
Module = $ModuleName
61-
Locale = $Locale
62-
OutputFolder = [IO.Path]::Combine($DocsPath, $Locale)
63-
ErrorAction = 'SilentlyContinue'
64-
Verbose = $VerbosePreference
81+
Module = $ModuleName
82+
Locale = $Locale
83+
OutputFolder = [IO.Path]::Combine($DocsPath, $Locale)
84+
AlphabeticParamsOrder = $AlphabeticParamsOrder
85+
ExcludeDontShow = $ExcludeDontShow
86+
UseFullTypeName = $UseFullTypeName
87+
ErrorAction = 'SilentlyContinue'
88+
Verbose = $VerbosePreference
6589
}
6690
if ($Overwrite) {
6791
$newMDParams.Add('Force', $true)

‎PowerShellBuild/build.properties.ps1‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,18 @@ $moduleVersion = (Import-PowerShellDataFile -Path $env:BHPSModuleManifest).Modul
115115

116116
# Whether to overwrite existing markdown files and use comment based help as the source of truth
117117
Overwrite = $false
118+
119+
# Whether to order parameters alphabetically by name in PARAMETERS section.
120+
# Value passed to New-MarkdownHelp and Update-MarkdownHelp.
121+
AlphabeticParamsOrder = $false
122+
123+
# Exclude the parameters marked with `DontShow` in the parameter attribute from the help content.
124+
# Value passed to New-MarkdownHelp and Update-MarkdownHelp.
125+
ExcludeDontShow = $false
126+
127+
# Indicates that the target document will use a full type name instead of a short name for parameters.
128+
# Value passed to New-MarkdownHelp and Update-MarkdownHelp.
129+
UseFullTypeName = $false
118130
}
119131
Publish = @{
120132
# PowerShell repository name to publish modules to

‎PowerShellBuild/psakeFile.ps1‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -124,11 +124,14 @@ $genMarkdownPreReqs = {
124124
}
125125
Task GenerateMarkdown -depends $PSBPreference.TaskDependencies.GenerateMarkdown -precondition $genMarkdownPreReqs {
126126
$buildMDParams = @{
127-
ModulePath = $PSBPreference.Build.ModuleOutDir
128-
ModuleName = $PSBPreference.General.ModuleName
129-
DocsPath = $PSBPreference.Docs.RootDir
130-
Locale = $PSBPreference.Help.DefaultLocale
131-
Overwrite = $PSBPreference.Docs.Overwrite
127+
ModulePath = $PSBPreference.Build.ModuleOutDir
128+
ModuleName = $PSBPreference.General.ModuleName
129+
DocsPath = $PSBPreference.Docs.RootDir
130+
Locale = $PSBPreference.Help.DefaultLocale
131+
Overwrite = $PSBPreference.Docs.Overwrite
132+
AlphabeticParamsOrder = $PSBPreference.Docs.AlphabeticParamsOrder
133+
ExcludeDontShow = $PSBPreference.Docs.ExcludeDontShow
134+
UseFullTypeName = $PSBPreference.Docs.UseFullTypeName
132135
}
133136
Build-PSBuildMarkdown @buildMDParams
134137
} -description 'Generates PlatyPS markdown files from module help'

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,9 @@ match your environment.
120120
| $PSBPreference.Help.ConvertReadMeToAboutHelp | `$false` | Convert project readme into the module about file |
121121
| $PSBPreference.Docs.RootDir | `$projectRoot/docs` | Directory PlatyPS markdown documentation will be saved to |
122122
| $PSBPreference.Docs.Overwrite | `$false` | Overwrite the markdown files in the docs folder using the comment based help as the source of truth. |
123+
| $PSBPreference.Docs.AlphabeticParamsOrder | `$false` | Order parameters alphabetically by name in PARAMETERS section. There are 5 exceptions: -Confirm, -WhatIf, -IncludeTotalCount, -Skip, and -First parameters will be the last. |
124+
| $PSBPreference.Docs.ExcludeDontShow | `$false` | Exclude the parameters marked with `DontShow` in the parameter attribute from the help content. |
125+
| $PSBPreference.Docs.UseFullTypeName | `$false` | Indicates that the target document will use a full type name instead of a short name for parameters. |
123126
| $PSBPreference.Publish.PSRepository | `PSGallery` | PowerShell repository name to publish |
124127
| $PSBPreference.Publish.PSRepositoryApiKey | `$env:PSGALLERY_API_KEY` | API key to authenticate to PowerShell repository with |
125128
| $PSBPreference.Publish.PSRepositoryCredential | `$null` | Credential to authenticate to PowerShell repository with. Overrides `$psRepositoryApiKey` if defined |

0 commit comments

Comments
 (0)