DscResource.DocGenerator

Functionality to help generate documentation for modules.

Code of Conduct

This project has adopted this Code of Conduct.

Releases

For each merge to the branch main a preview release will be deployed to PowerShell Gallery. Periodically a release version tag will be pushed which will deploy a full release to PowerShell Gallery.

Contributing

Please check out the DSC Community contributing guidelines. This repository align to the DSC Community Style Guidelines.

Known Issues

Composite Resources and Linux

The cmdlets and tasks that generate documentation for composite resources require the configuration statement that is provided by DSC. DSC is not installed on Linux by default, so these cmdlets This cmdlet will fail on Linux if the DSC resource module contains any composite resources. To enable these cmdlets to work on Linux, please install PowerShell DSC for Linux.

Cmdlets

Refer to the comment-based help for more information about these helper functions.

Get-Help -Name <CmdletName> -Detailed

New-DscResourcePowerShellHelp

Generates conceptual help based on the DSC resources and their examples in a DSC module. This currently only creates English (culture en-US) conceptual help. MOF, class-based and composite resources are supported. Class-based resources must follow the template pattern of the Sampler project. See the project AzureDevOpDsc for an example of the pattern.

After the conceptual help has been created, the user can import the module and for example run Get-Help about_UserAccountControl to get help about the DSC resource UserAccountControl.

It is possible to pass a array of regular expressions that should be used to parse the parameter descriptions in the schema MOF. The regular expression must be written so that the capture group 0 is the full match and the capture group 1 is the text that should be kept.

NOTE: This cmdlet does not work on macOS and will throw an error due to the problem discussed in issue PowerShell/PowerShell#5970 and issue PowerShell/MMI#33.

Syntax

New-DscResourcePowerShellHelp [-ModulePath] <string> [[-DestinationModulePath] <string>] 
  [[-OutputPath] <string>] [[-MarkdownCodeRegularExpression] <string[]>]
  [<CommonParameters>]

Outputs

None.

Example

cd c:\source\MyDscModule

New-DscResourcePowerShellHelp -ModulePath '.'

New-DscResourceWikiPage

Generate documentation that can be manually uploaded to the GitHub repository Wiki.

Syntax

New-DscResourceWikiPage [-OutputPath] <string> [-ModulePath] <string> [<CommonParameters>]

Outputs

None.

Example

cd c:\source\MyDscModule

New-DscResourceWikiPage -ModulePath '.' -OutputPath '.\output\WikiContent'

Publish-WikiContent

Publishes the Wiki content that was generated by the cmdlet New-DscResourceWikiPage.

NOTE: There must already be a Wiki created in the GitHub repository before using this cmdlet.

Syntax

Publish-WikiContent [-Path] <string> [-OwnerName] <string> [-RepositoryName] <string>
  [-ModuleName] <string> [-ModuleVersion] <string> [-GitHubAccessToken] <string>
  [-GitUserEmail] <string> [-GitUserName] <string>
  [[-GlobalCoreAutoCrLf] {true | false | input}] [<CommonParameters>]

Outputs

None.

Example

cd c:\source\MyDscModule

Publish-WikiContent `
    -Path '.\output\WikiContent' `
    -OwnerName 'dsccommunity' `
    -RepositoryName 'SqlServerDsc' `
    -ModuleName 'SqlServerDsc' `
    -ModuleVersion '14.0.0' `
    -GitHubAccessToken 'token' `
    -GitUserEmail '[email protected]' `
    -GitUserName 'dsc' `

Adds the content pages in '.\output\WikiContent' to the Wiki for the specified GitHub repository.

cd c:\source\MyDscModule

Publish-WikiContent `
    -Path '.\output\WikiContent' `
    -OwnerName 'dsccommunity' `
    -RepositoryName 'SqlServerDsc' `
    -ModuleName 'SqlServerDsc' `
    -ModuleVersion '14.0.0' `
    -GitHubAccessToken 'token' `
    -GitUserEmail '[email protected]' `
    -GitUserName 'dsc' `
    -WikiSourcePath '.\source\WikiSource' `

Adds the content pages in '.\output\WikiContent' plus the content from '.\source\WikiSource' to the Wiki for the specified GitHub repository.

cd c:\source\MyDscModule

Publish-WikiContent `
    -Path '.\output\WikiContent' `
    -OwnerName 'dsccommunity' `
    -RepositoryName 'SqlServerDsc' `
    -ModuleName 'SqlServerDsc' `
    -ModuleVersion '14.0.0' `
    -GitHubAccessToken 'token' `
    -GitUserEmail '[email protected]' `
    -GitUserName 'dsc' `
    -GlobalCoreAutoCrLf 'true'

Adds the content pages in '.\output\WikiContent' to the Wiki for the specified GitHub repository. The wiki repository will be cloned after the git configuration setting --global core.autocrlf have been set to true making sure the current wiki files are checkout using CRLF.

Set-WikiModuleVersion

Changes all placeholders (#.#.#) in a markdown file to the specified module version.

Syntax

Set-WikiModuleVersion [-Path] <string> [-ModuleVersion] <string> [<CommonParameters>]

Outputs

None.

Example

Set-WikiModuleVersion -Path '.\output\WikiContent\Home.md' -ModuleVersion '14.0.0'

Replaces '#.#.#' with the module version '14.0.0' in the markdown file 'Home.md'.

Split-ModuleVersion

This function parses a module version string as returns a hashtable which each of the module version's parts.

Syntax

Split-ModuleVersion [[-ModuleVersion] <string>] [<CommonParameters>]

Outputs

System.Management.Automation.PSCustomObject

Example

Split-ModuleVersion -ModuleVersion '1.15.0-pr0224-0022+Sha.47ae45eb'

Splits the module version an returns a PSCustomObject with the parts of the module version.

Version PreReleaseString ModuleVersion
------- ---------------- -------------
1.15.0  pr0224           1.15.0-pr0224

Tasks

These are Invoke-Build tasks. The build tasks are primarily meant to be run by the project Sampler's build.ps1 which wraps Invoke-Build and has the configuration file (build.yaml) to control its behavior.

To make the tasks available for the cmdlet Invoke-Build in a repository that is based on the Sampler project, add this module to the file RequiredModules.psd1 and then in the file build.yaml add the following:

ModuleBuildTasks:
  DscResource.DocGenerator:
    - 'Task.*'

Generate_Conceptual_Help

This build task runs the cmdlet New-DscResourcePowerShellHelp.

Below is an example how the build task can be used when a repository is based on the Sampler project.

BuildWorkflow:
  '.':
    - build

  build:
    - Clean
    - Build_Module_ModuleBuilder
    - Build_NestedModules_ModuleBuilder
    - Create_changelog_release_output
    - Generate_Conceptual_Help

If the schema mof property descriptions contain markdown code then it is possible to configure regular expressions to remove the markdown code. The regular expressions must be written so that capture group 0 returns the full match and the capture group 1 returns the text that should be kept. For example the regular expression \`(.+?)\` will find `$true` which will be replaced to $true since that is what will be returned by capture group 1.

Below is some example regular expressions for the most common markdown code.

NOTE: Each regular expression must be able to find multiple matches on the same row.

DscResource.DocGenerator:
  Generate_Conceptual_Help:
    MarkdownCodeRegularExpression:
      - '\`(.+?)\`' # Match inline code-block
      - '\\(\\)' # Match escaped backslash
      - '\[[^\[]+\]\((.+?)\)' # Match markdown URL
      - '_(.+?)_' # Match Italic (underscore)
      - '\*\*(.+?)\*\*' # Match bold
      - '\*(.+?)\*' # Match Italic (asterisk)

NOTE: If the task is used in a module that is using the project Sampler's build.ps1 then version 0.102.1 of Sampler is required.

Generate_Wiki_Content

This build task runs the cmdlet New-DscResourceWikiPage to build documentation for DSC resources. It will also copy the content of the wiki source folder if it exist (WikiSourceFolderName defaults to WikiSource).

if the Home.md is present in the folder specified in WikiSourceFolderName all module version placeholders (#.#.#) will be replaced with the built module version.

It is possible to use markdown code in the schema MOF parameter descriptions if no conceptual help is generated or the generation of conceptual help is configured to parse markdown code. See the task Generate_Conceptual_Help for more information.

Below is an example how the build task can be used when a repository is based on the Sampler project.

BuildWorkflow:
  '.':
    - build

  build:
    - Clean
    - Build_Module_ModuleBuilder
    - Build_NestedModules_ModuleBuilder
    - Create_changelog_release_output
    - Generate_Wiki_Content

Publish_GitHub_Wiki_Content

This build task runs the cmdlet Publish-WikiContent. The task will only run if the variable $GitHubToken is set either in parent scope, as an environment variable, or if passed to the build task.

Below is an example how the build task can be used when a repository is based on the Sampler project.

NOTE: This task is meant to be run after the task Generate_Wiki_Content that is normally run in the build phase. But this task can be used to upload any content to a Wiki.

BuildWorkflow:
  '.':
    - build

  build:
    - Clean
    - Build_Module_ModuleBuilder
    - Build_NestedModules_ModuleBuilder
    - Create_changelog_release_output
    - Generate_Wiki_Content

  publish:
    - Publish_release_to_GitHub
    - publish_module_to_gallery
    - Publish_GitHub_Wiki_Content