Write-MFModuleDocs

SYNOPSIS

Generates and updates function documentation using Microsoft.PowerShell.PlatyPS, and creates an index for module functions.

SYNTAX

All parameter sets

Write-MFModuleDocs [[-ModulePath] <string>] [-ModuleName] <string> [[-DocsFolder] <string>]
 [[-FunctionsFolder] <string>] [-IncludeChangeLog] [-SkipIndex] [-StampAllDocs]

ALIASES

This cmdlet has the following aliases,

DESCRIPTION

Automates documentation generation based on module functions, leveraging Microsoft.PowerShell.PlatyPS to create Markdown help files. Injects Just The Docs front matter into every generated page so the Jekyll sidebar renders a proper navigation hierarchy without manual editing.

Needs Microsoft.PowerShell.PlatyPS 1.0 or newer. The older platyPS 0.14 module is no longer used.

PlatyPS front matter that changes with the machine or the day, ms.date and Locale, is dropped, so regenerating the docs only changes pages whose help actually changed.

The -StampAllDocs switch extends that treatment to the entire docs folder: it scans every subdirectory, creates parent index pages with child link lists, and non-destructively injects front matter into any page that does not already carry a ‘layout:’ field. Pages with existing Just The Docs front matter are never modified.

EXAMPLES

EXAMPLE 1

Write-MFModuleDocs -ModuleName ‘MyCustomModule’ -IncludeChangeLog

DESCRIPTION

Builds documentation for MyCustomModule and includes a full Git-based changelog alongside function help files.

EXAMPLE 2

Write-MFModuleDocs -ModuleName ‘MyCustomModule’ -StampAllDocs -IncludeChangeLog

DESCRIPTION

Generates function docs, stamps all existing docs pages with Just The Docs front matter, and produces a changelog. Ideal for a CI pipeline docs update step.

EXAMPLE 3

Write-MFModuleDocs -ModuleName ‘MyCustomModule’ -SkipIndex

DESCRIPTION

Generates function documentation without updating index.md.

PARAMETERS

-DocsFolder

Specify the docs folder. All files and index.md will be created here and in subfolders. Defaults to ‘docs’.

Type: System.String
DefaultValue: docs
SupportsWildcards: false
Aliases:
- docsPath
ParameterSets:
- Name: (All)
  Position: 2
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-FunctionsFolder

Subfolder within DocsFolder where function documentation is stored. Defaults to ‘functions’.

Type: System.String
DefaultValue: functions
SupportsWildcards: false
Aliases:
- functionsPath
ParameterSets:
- Name: (All)
  Position: 3
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-IncludeChangeLog

If specified, retrieves and includes a Markdown changelog based on Git commit history.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ModuleName

The name of the PowerShell module for which documentation should be generated.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases:
- module
ParameterSets:
- Name: (All)
  Position: 1
  IsRequired: true
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ModulePath

The root path where documentation should be stored. Defaults to the current directory.

Type: System.String
DefaultValue: $(get-item .).fullname
SupportsWildcards: false
Aliases:
- Path
ParameterSets:
- Name: (All)
  Position: 0
  IsRequired: false
  ValueFromPipeline: true
  ValueFromPipelineByPropertyName: true
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-SkipIndex

If specified, skips creating or updating the index.md homepage.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-StampAllDocs

If specified, scans all subdirectories of the docs folder and non-destructively injects Just The Docs front matter into pages that do not already have a ‘layout:’ field. Creates parent index pages with child link lists where none exist.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

[string] - ModulePath is accepted as pipeline input or via direct assignment.

System.String

OUTPUTS

NOTES

Author: Adrian Andersson