Skip to content

Commit 194de8b

Browse files
author
Chris Hunt
committed
Update Help
1 parent 85d2f28 commit 194de8b

17 files changed

+361
-97
lines changed

‎README.md‎

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,55 @@
22

33
Helper for building markdown docs from PowerShell Command Help.
44

5+
## CI Status
6+
7+
[![PowerShell](https://github.com/cdhunt/Build-Docs/actions/workflows/powershell.yml/badge.svg)](https://github.com/cdhunt/Build-Docs/actions/workflows/powershell.yml)
8+
59
## Install
610

7-
TBD
11+
[powershellgallery.com/packages/Build-Docs](https://www.powershellgallery.com/packages/Build-Docs)
12+
13+
`Install-Module -Name Build-Docs` or `Install-PSResource -Name Build-Docs`
814

915
## Docs
1016

1117
[Full Docs](docs)
1218

19+
### Getting Started
20+
21+
This module will walk the properties and help for each command in a given module and add a `.ToMD()` ScriptMethod that applies some opinionated markdown formatting. The is entirely based on the output of [Get-Help](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/get-help?view=powershell-7.4) so the help data can be XML-based or comment-based.
22+
23+
This module adds the `.ToMD()` method to the following command help properties.
24+
25+
- `Description`
26+
- `ParameterSet` _(each)_: Adds an H3 header for each parameter set which contains a unordered list of parameters.
27+
- `Example` _(each)_: All of the text before an empty newline is considered part of the code and will be fenced in a code block. Text after an empty newline is considered the Remarks.
28+
- `Link` _(each)_: Format as a HREF link. If the link text is an existing command in the module it will link to `{commandname}.md`.
29+
- `Note`
30+
- `Output`
31+
32+
### Example Usage
33+
34+
This is the basic snippet I use in my `build.ps1` scripts to generate all the files under `/docs`.
35+
36+
```powershell
37+
$help = Get-HelpModuleData $module
38+
39+
# docs/README.md
40+
$help | New-HelpDoc |
41+
Add-ModuleProperty Name -H1 |
42+
Add-ModuleProperty Description |
43+
Add-HelpDocText "Commands" -H2 |
44+
Add-ModuleCommand -AsLinks |
45+
Out-HelpDoc -Path 'docs/README.md'
46+
47+
# Individual Commands
48+
foreach ($command in $help.Commands) {
49+
$name = $command.Name
50+
$doc = New-HelpDoc -HelpModuleData $help
51+
$doc.Text = $command.ToMD()
52+
$doc | Out-HelpDoc -Path "docs/$name.md"
53+
}
54+
```
55+
1356

‎build.ps1‎

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -175,19 +175,14 @@ function Publish {
175175
function Docs {
176176
param ()
177177

178+
if ($null -eq (Get-Module Build-Docs -ListAvailable | Where-Object { [version]$_.Version -ge [version]"0.2.0.2" })) {
179+
Install-Module -Name Build-Docs -MinimumVersion 0.2.0.2 -Confirm:$false -Force
180+
}
181+
178182
Import-Module $publish -Force
179183

180184
$help = Get-HelpModuleData $module
181185

182-
$help | New-HelpDoc |
183-
Add-ModuleProperty Name -H1 |
184-
Add-ModuleProperty Description |
185-
Add-HelpDocText 'Install' -H2 |
186-
Add-HelpDocText 'TBD' |
187-
Add-HelpDocText 'Docs' -H2 |
188-
Add-HelpDocText '[Full Docs](docs)' |
189-
Out-HelpDoc -Path 'README.md'
190-
191186
# docs/README.md
192187
$help | New-HelpDoc |
193188
Add-ModuleProperty Name -H1 |

‎docs/Add-HelpDocText.md‎

Lines changed: 30 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,48 @@
11
# Add-HelpDocText
22

3-
4-
Add-HelpDocText [-Text] <string> [-HelpDoc] <psobject> [<CommonParameters>]
5-
6-
Add-HelpDocText [-Text] <string> [-HelpDoc] <psobject> [-H3] [<CommonParameters>]
7-
8-
Add-HelpDocText [-Text] <string> [-HelpDoc] <psobject> [-H2] [<CommonParameters>]
9-
10-
Add-HelpDocText [-Text] <string> [-HelpDoc] <psobject> [-H1] [<CommonParameters>]
11-
3+
Return the given string optionally formatted as a Header.
124

135
## Parameters
146

157
### Parameter Set 1
168

17-
- `[string]` **Text** _Parameter help description_ Mandatory
18-
- `[psobject]` **HelpDoc** _Parameter help description_ Mandatory, ValueFromPipeline
9+
- `[PSObject]` **HelpDoc** _A HelpDoc object._ Mandatory, ValueFromPipeline
10+
- `[String]` **Text** _A string to add to the HelpDoc._ Mandatory
1911

2012
### Parameter Set 2
2113

22-
- `[string]` **Text** _Parameter help description_ Mandatory
23-
- `[psobject]` **HelpDoc** _Parameter help description_ Mandatory, ValueFromPipeline
24-
- `[Switch]` **H3** _Parameter help description_
14+
- `[PSObject]` **HelpDoc** _A HelpDoc object._ Mandatory, ValueFromPipeline
15+
- `[String]` **Text** _A string to add to the HelpDoc._ Mandatory
16+
- `[Switch]` **H3** _Format the text as an H3 header._
2517

2618
### Parameter Set 3
2719

28-
- `[string]` **Text** _Parameter help description_ Mandatory
29-
- `[psobject]` **HelpDoc** _Parameter help description_ Mandatory, ValueFromPipeline
30-
- `[Switch]` **H2** _Parameter help description_
20+
- `[PSObject]` **HelpDoc** _A HelpDoc object._ Mandatory, ValueFromPipeline
21+
- `[String]` **Text** _A string to add to the HelpDoc._ Mandatory
22+
- `[Switch]` **H2** _Format the text as an H2 header._
3123

3224
### Parameter Set 4
3325

34-
- `[string]` **Text** _Parameter help description_ Mandatory
35-
- `[psobject]` **HelpDoc** _Parameter help description_ Mandatory, ValueFromPipeline
36-
- `[Switch]` **H1** _Parameter help description_
26+
- `[PSObject]` **HelpDoc** _A HelpDoc object._ Mandatory, ValueFromPipeline
27+
- `[String]` **Text** _A string to add to the HelpDoc._ Mandatory
28+
- `[Switch]` **H1** _Format the text as an H1 header._
29+
30+
## Examples
31+
32+
### Example 1
33+
34+
Add a level 1 header with the text "My Module Help".
35+
36+
```powershell
37+
Get-HelpModuleData build-docs | New-HelpDoc | Add-HelpDocText -Text "My Module Help" -H1 | Out-HelpDoc
38+
# My Module Help
39+
```
40+
41+
## Links
42+
43+
- [New-HelpDoc](New-HelpDoc.md)
44+
- [Get-HelpModuleData](Get-HelpModuleData.md)
3745

38-
## Outputs
46+
## Notes
3947

40-
- `System.Object`
48+
If no Header switch is provided, the default is no formatting.

‎docs/Add-ModuleCommand.md‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,27 @@
11
# Add-ModuleCommand
22

3-
4-
Add-ModuleCommand [-HelpDoc] <psobject> [-AsLinks] [<CommonParameters>]
5-
3+
Generate a Markdown list of the commands in the module and optionally format as links.
64

75
## Parameters
86

97
### Parameter Set 1
108

11-
- `[psobject]` **HelpDoc** _Parameter help description_ Mandatory, ValueFromPipeline
12-
- `[Switch]` **AsLinks** _Parameter help description_
9+
- `[PSObject]` **HelpDoc** _A HelpDoc object._ Mandatory, ValueFromPipeline
10+
- `[Switch]` **AsLinks** _Format each list item as a link to a `{commandname}.md`._
11+
12+
## Examples
13+
14+
### Example 1
15+
16+
Generate a list of commands with links to the commands' help documents.
17+
18+
```powershell
19+
Get-HelpModuleData build-docs | New-HelpDoc | Add-ModuleCommand -AsLinks | select -exp Text
20+
- [Add-HelpDocText](Add-HelpDocText.md) _Return a markdown formatted text._
21+
- [Add-ModuleCommand](Add-ModuleCommand.md) _Generate a Markdown list of the commands in the module._
22+
- [Add-ModuleProperty](Add-ModuleProperty.md) _Return a markdown formatted value for the given property._
23+
…
24+
```
1325

14-
## Outputs
26+
## Links
1527

16-
- `System.Object`

‎docs/Add-ModuleProperty.md‎

Lines changed: 34 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,52 @@
11
# Add-ModuleProperty
22

3-
4-
Add-ModuleProperty [-Property] <string> [-HelpDoc] <psobject> [<CommonParameters>]
5-
6-
Add-ModuleProperty [-Property] <string> [-HelpDoc] <psobject> [-H3] [<CommonParameters>]
7-
8-
Add-ModuleProperty [-Property] <string> [-HelpDoc] <psobject> [-H2] [<CommonParameters>]
9-
10-
Add-ModuleProperty [-Property] <string> [-HelpDoc] <psobject> [-H1] [<CommonParameters>]
11-
3+
Return the value for the given property optionally formatted as a Header.
124

135
## Parameters
146

157
### Parameter Set 1
168

17-
- `[string]` **Property** _Parameter help description_ Mandatory
18-
- `[psobject]` **HelpDoc** _Parameter help description_ Mandatory, ValueFromPipeline
9+
- `[PSObject]` **HelpDoc** _A HelpDoc object._ Mandatory, ValueFromPipeline
10+
- `[String]` **Property** _A top level property from the Help object. Valid values are `'Name'`, `'Author'`, `'Description'`, `'HelpInfoUri'`, `'LicenseUri'`, `'ProjectUri'`, and `'Version'`._ Mandatory
1911

2012
### Parameter Set 2
2113

22-
- `[string]` **Property** _Parameter help description_ Mandatory
23-
- `[psobject]` **HelpDoc** _Parameter help description_ Mandatory, ValueFromPipeline
24-
- `[Switch]` **H3** _Parameter help description_
14+
- `[PSObject]` **HelpDoc** _A HelpDoc object._ Mandatory, ValueFromPipeline
15+
- `[String]` **Property** _A top level property from the Help object. Valid values are `'Name'`, `'Author'`, `'Description'`, `'HelpInfoUri'`, `'LicenseUri'`, `'ProjectUri'`, and `'Version'`._ Mandatory
16+
- `[Switch]` **H3** _Format the property value as an H3 header._
2517

2618
### Parameter Set 3
2719

28-
- `[string]` **Property** _Parameter help description_ Mandatory
29-
- `[psobject]` **HelpDoc** _Parameter help description_ Mandatory, ValueFromPipeline
30-
- `[Switch]` **H2** _Parameter help description_
20+
- `[PSObject]` **HelpDoc** _A HelpDoc object._ Mandatory, ValueFromPipeline
21+
- `[String]` **Property** _A top level property from the Help object. Valid values are `'Name'`, `'Author'`, `'Description'`, `'HelpInfoUri'`, `'LicenseUri'`, `'ProjectUri'`, and `'Version'`._ Mandatory
22+
- `[Switch]` **H2** _Format the property value as an H2 header._
3123

3224
### Parameter Set 4
3325

34-
- `[string]` **Property** _Parameter help description_ Mandatory
35-
- `[psobject]` **HelpDoc** _Parameter help description_ Mandatory, ValueFromPipeline
36-
- `[Switch]` **H1** _Parameter help description_
26+
- `[PSObject]` **HelpDoc** _A HelpDoc object._ Mandatory, ValueFromPipeline
27+
- `[String]` **Property** _A top level property from the Help object. Valid values are `'Name'`, `'Author'`, `'Description'`, `'HelpInfoUri'`, `'LicenseUri'`, `'ProjectUri'`, and `'Version'`._ Mandatory
28+
- `[Switch]` **H1** _Format the property value as an H1 header._
29+
30+
## Examples
31+
32+
### Example 1
33+
34+
35+
36+
```powershell
37+
Get-HelpModuleData build-docs | New-HelpDoc | Add-ModuleProperty -Property Name -H1
38+
Name Value
39+
---- -----
40+
Text # build-docs…
41+
PSTypeName HelpModuleReadme
42+
HelpModuleData @{Name=build-docs; Commands=System.Object[]; Author=System.Object[]; Description=System.Object[]; …
43+
```
44+
45+
## Links
46+
47+
- [New-HelpDoc](New-HelpDoc.md)
48+
- [Get-HelpModuleData](Get-HelpModuleData.md)
3749

38-
## Outputs
50+
## Notes
3951

40-
- `System.Object`
52+
If no Header switch is provided, the default is no formatting.

‎docs/Get-HelpCommandData.md‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,31 @@
11
# Get-HelpCommandData
22

3-
4-
Get-HelpCommandData [-Name] <string> [<CommonParameters>]
5-
6-
Get-HelpCommandData [-HelpSource] <psobject> [<CommonParameters>]
7-
3+
A longer description of the function, its purpose, common use cases, etc.
84

95
## Parameters
106

117
### Parameter Set 1
128

13-
- `[string]` **Name** _Parameter help description_ Mandatory, ValueFromPipeline
9+
- `[String]` **Name** _Parameter help description_ Mandatory, ValueFromPipeline
1410

1511
### Parameter Set 2
1612

17-
- `[psobject]` **HelpSource** _Parameter help description_ Mandatory, ValueFromPipeline
13+
- `[PSObject]` **HelpSource** _Parameter help description_ Mandatory, ValueFromPipeline
14+
15+
## Examples
16+
17+
### Example 1
18+
19+
20+
21+
```powershell
22+
Test-MyTestFunction -Verbose
23+
Explanation of the function or its result. You can include multiple examples with additional .EXAMPLE lines
24+
```
25+
26+
## Links
27+
1828

19-
## Outputs
29+
## Notes
2030

21-
- `System.Object`
31+
Information or caveats about the function e.g. 'This function is not supported in Linux'

‎docs/Get-HelpModuleData.md‎

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,29 @@
11
# Get-HelpModuleData
22

3-
4-
Get-HelpModuleData [-Name] <string> [<CommonParameters>]
5-
3+
Returns an object representation of the help available for the given module. This includes the help for each command in the module.
64

75
## Parameters
86

97
### Parameter Set 1
108

11-
- `[string]` **Name** _Parameter help description_ Mandatory, ValueFromPipeline
9+
- `[String]` **Name** _The name of the module to interrogate for help data._ Mandatory, ValueFromPipeline
10+
11+
## Examples
12+
13+
### Example 1
14+
15+
Returns an object representation of the help available for the given module.
16+
17+
```powershell
18+
Get-HelpModuleData build-docs
19+
Name : build-docs
20+
Commands : {@{Name=Add-HelpDocText; Synopsis=
21+
Add-HelpDocText [-Text] <string> [-HelpDoc] <psobject> [<CommonParameters>]
22+
Add-HelpDocText [-Text] <string> [-HelpDoc] <psobject> [-H3] [<CommonParameters>]
23+
Add-HelpDocText [-Text] <string> [-HelpDoc] <psobject> [-H2] [<CommonParameters>]
24+
…
25+
```
1226

13-
## Outputs
27+
## Links
1428

15-
- `System.Object`
29+
- [New-HelpDoc](New-HelpDoc.md)

‎docs/New-HelpDoc.md‎

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,33 @@
11
# New-HelpDoc
22

3-
4-
New-HelpDoc [-HelpModuleData] <psobject> [<CommonParameters>]
5-
3+
Returns an empty HelpModuleReadme object that is the object representation of your documentation.
64

75
## Parameters
86

97
### Parameter Set 1
108

11-
- `[psobject]` **HelpModuleData** _Parameter help description_ Mandatory, ValueFromPipeline
9+
- `[PSObject]` **HelpModuleData** _A HelpModuleData object._ Mandatory, ValueFromPipeline
10+
11+
## Examples
12+
13+
### Example 1
14+
15+
16+
17+
```powershell
18+
Get-HelpModuleData build-docs | New-HelpDoc
19+
Name Value
20+
---- -----
21+
Text
22+
PSTypeName HelpModuleReadme
23+
HelpModuleData @{Name=build-docs; Commands=System.Object[]; Author=System.Object[]; Description=System.Object[];
24+
```
25+
26+
## Links
27+
28+
- [Get-HelpModuleData](Get-HelpModuleData.md)
29+
- [Out-HelpDoc](Out-HelpDoc.md)
1230

1331
## Outputs
1432

15-
- `System.Collections.Hashtable
16-
`
33+
- `HelpModuleReadme`

0 commit comments

Comments
 (0)