New-ConfigurationDocumentation

Namespace PSPublishModule

Inputs

None

Enables or disables creation of documentation from the module using PowerForge.

Remarks

This cmdlet emits documentation configuration segments that are consumed by Invoke-ModuleBuild / Build-Module. It controls markdown generation (in -Path), optional external help generation (MAML, e.g. en-US\<ModuleName>-help.xml), and project-root documentation sync. When -Enable is used, PowerForge generates documentation, cleans stale files in the configured docs folder, and updates the project documentation path by default. About topics are supported via about_*.help.txt / about_*.txt / about_*.md / about_*.markdown files present in the module source. When enabled, these are converted into markdown pages under Docs\About. Additional source roots can be provided via AboutTopicsSourcePath.

Examples

Authored help example

Generate markdown docs and external help, and update the project docs folder


New-ConfigurationDocumentation -Enable -Path 'Docs' -PathReadme 'Docs\Readme.md' -SyncExternalHelpToProjectRoot

Generate docs but skip about topics conversion and fallback examples


New-ConfigurationDocumentation -Enable -Path 'Docs' -PathReadme 'Docs\Readme.md' -SkipAboutTopics -SkipFallbackExamples

Generate docs and scan custom about topic folders in staging


New-ConfigurationDocumentation -Enable -Path 'Docs' -PathReadme 'Docs\Readme.md' -AboutTopicsSourcePath 'Help\About','Internals\About'

Common Parameters

This command supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.

For more information, see about_CommonParameters.

Syntax

New-ConfigurationDocumentation [-AboutTopicsSourcePath <String[]>] [-Enable] [-ExternalHelpCulture <String>] [-ExternalHelpFileName <String>] -Path <String> -PathReadme <String> [-SkipAboutTopics] [-SkipExternalHelp] [-SkipFallbackExamples] [-StartClean] [-SyncExternalHelpToProjectRoot] [-UpdateWhenNew] [<CommonParameters>]

Parameter set: All Parameter Sets

Parameters

AboutTopicsSourcePath String[] optionalposition: namedpipeline: False: Optional extra source paths for about_* topic files (.help.txt, .txt, .md, .markdown). Relative paths are resolved from the staging root (for example: 'Help\About').
Enable SwitchParameter optionalposition: namedpipeline: False: Enables creation of documentation from the module.
ExternalHelpCulture String optionalposition: namedpipeline: False: Culture folder for generated external help (default: en-US).
ExternalHelpFileName String optionalposition: namedpipeline: False: Optional file name override for external help (default: <ModuleName>-help.xml).
Path String requiredposition: namedpipeline: False: Path to the folder where documentation will be created.
PathReadme String requiredposition: namedpipeline: False: Path to the readme file that will be used for the documentation.
SkipAboutTopics SwitchParameter optionalposition: namedpipeline: False: Disable conversion of about_* topics into markdown pages.
SkipExternalHelp SwitchParameter optionalposition: namedpipeline: False: Disable external help (MAML) generation.
SkipFallbackExamples SwitchParameter optionalposition: namedpipeline: False: Disable generating basic fallback examples for cmdlets missing examples.
StartClean SwitchParameter optionalposition: namedpipeline: False: Legacy compatibility switch. Documentation builds clean stale generated files by default.
SyncExternalHelpToProjectRoot SwitchParameter optionalposition: namedpipeline: False: When enabled, the generated external help file is also synced back to the project root (e.g. en-US\<ModuleName>-help.xml).
UpdateWhenNew SwitchParameter optionalposition: namedpipeline: False: Legacy compatibility switch. Documentation builds update the project documentation path by default.