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 master 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.

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 mof-based DSC resources and their examples in a DSC module. This currently only creates english (culture en-US) conceptual help.

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@contoso.com' `
    -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@contoso.com' `
    -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@contoso.com' `
    -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'.

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