Skip to content

Latest commit

 

History

History
558 lines (426 loc) · 17.3 KB

README.md

File metadata and controls

558 lines (426 loc) · 17.3 KB
Raw

DscResource.DocGenerator

Functionality to help generate documentation for modules.

Build Status Azure DevOps coverage (branch) codecov Azure DevOps tests PowerShell Gallery (with prereleases) PowerShell Gallery

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 common DSC Community contributing guidelines. This repository align to the DSC Community Style Guidelines.

Change log

A full list of changes in each version can be found in the change log.

Known Issues

Composite Resources and Linux

The commands 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 commands will fail on Linux if the DSC resource module contains any composite resources. To enable these commands to work on Linux, please install PowerShell DSC for Linux.

Commands

Refer to the repository Wiki for more information about the commands.

The information is also available in the comment-based help by running:

Get-Help -Name <CmdletName> -Detailed

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 command 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.*'

Clean_Markdown_Of_Public_Commands

This build task runs the command Edit-CommandDocumentation on each markdown file that was generated by the task Generate_Markdown_For_Public_Commands.

See the command Edit-CommandDocumentation for more information.

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 tasks Generate_Markdown_For_Public_Commands and Generate_Wiki_Content, but before the task Clean_Markdown_Metadata.

BuildWorkflow:
  '.':
    - build

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

  publish:
    - Publish_release_to_GitHub
    - publish_module_to_gallery
    - Publish_GitHub_Wiki_Content

Clean_Markdown_Metadata

This build task runs the command Remove-MarkdownMetadataBlock on each markdown file that is present in the folder provided by the parameter DocOutputFolder (defaults to ./output/WikiContent).

See the command Remove-MarkdownMetadataBlock for more information.

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 all tasks that generate of modifies markdown.

BuildWorkflow:
  '.':
    - build

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

  publish:
    - Publish_release_to_GitHub
    - publish_module_to_gallery
    - Publish_GitHub_Wiki_Content

Clean_WikiContent_For_GitHub_Publish

Important

This task does not work in Windows PowerShell due to it not supporting unicode in filenames.

This build task will clean the markdown files for publishing to the GitHub Wiki. It can be controlled by parameter RemoveTopLevelHeader in the task, which defaults to $true.

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_Markdown_For_Public_Commands
    - Clean_WikiContent_For_GitHub_Publish

Copy_Source_Wiki_Folder

This build task will copy the content of the wiki source folder if it exist (the parameter WikiSourceFolderName defaults to WikiSource). The wiki source folder should be located under the source folder, e.g. source/WikiSource. The wiki source folder is meant to contain additional documentation that will be added to folder WikiOutput during build, and then published to the wiki during the deploy stage (if either the command Publish-WikiContent or the task Publish_GitHub_Wiki_Content is used).

if the Home.md is present in the folder specified in WikiSourceFolderName it will be copied to WikiOutput and all module version placeholders (#.#.#) of the content the file will be replaced with the built module version.

Create_Wiki_Output_Folder

This build task creates the folder output/WikiContent.

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

BuildWorkflow:
  '.':
    - build

  docs:
    - Create_Wiki_Output_Folder
    - Generate_Markdown_For_Public_Commands
    - Clean_Markdown_Of_Public_Commands
    - Copy_Source_Wiki_Folder
    - Generate_Wiki_Sidebar
    - Clean_Markdown_Metadata
    - Package_Wiki_Content

Generate_Conceptual_Help

This build task runs the command 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_External_Help_File_For_Public_Commands

This build task runs the command New-ExternalHelp (PlatyPS command) that will generate an external help file for the module based on the generated markdown. See the command New-ExternalHelp for more information.

It is possible to pass HelpCultureInfo (default is en-US), it can be set either in parent scope, as an environment variable, or if passed as a parameter 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 tasks Generate_Markdown_For_Public_Commands, and it is meant that the task Clean_Markdown_Of_Public_Commands is ran after.

BuildWorkflow:
  '.':
    - build

  build:
    - Clean
    - Build_Module_ModuleBuilder
    - Build_NestedModules_ModuleBuilder
    - Create_changelog_release_output
    - Generate_Wiki_Content
    - Generate_Markdown_For_Public_Commands
    - Generate_External_Help_File_For_Public_Commands
    - Clean_Markdown_Of_Public_Commands

  publish:
    - Publish_release_to_GitHub
    - publish_module_to_gallery
    - Publish_GitHub_Wiki_Content

Generate_External_Help_File_For_Public_Commands

This build task runs the command New-ExternalHelp (PlatyPS command) that will generate an external help file for the module based on the generated markdown. See the command New-ExternalHelp for more information.

It is possible to pass HelpCultureInfo (default is en-US), it can be set either in parent scope, as an environment variable, or if passed as a parameter 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 tasks Generate_Markdown_For_Public_Commands, and it is meant that the task Clean_Markdown_Of_Public_Commands is ran after.

BuildWorkflow:
  '.':
    - build

  build:
    - Clean
    - Build_Module_ModuleBuilder
    - Build_NestedModules_ModuleBuilder
    - Create_changelog_release_output
    - Generate_Wiki_Content
    - Generate_Markdown_For_Public_Commands
    - Generate_External_Help_File_For_Public_Commands
    - Clean_Markdown_Of_Public_Commands

  publish:
    - Publish_release_to_GitHub
    - publish_module_to_gallery
    - Publish_GitHub_Wiki_Content

Generate_Markdown_For_Public_Commands

This build task runs the command New-MarkdownHelp (PlatyPS command) that will generate markdown for the module's public commands. See the command New-MarkdownHelp for more information.

It is possible to pass:

  • HelpCultureInfo (default is en-US)
  • DependentTypePath (default is an empty array)
  • DependentModule (default is an empty array)
  • WithModulePage (default is $false)
  • AlphabeticParamOrder (default is $true)
  • ExcludeDontShow (default is $true)

They can be set either in parent scope, as an environment variable, or if passed as a parameter to the build task.

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
    - Generate_Markdown_For_Public_Commands
    - Clean_Markdown_Of_Public_Commands

  publish:
    - Publish_release_to_GitHub
    - publish_module_to_gallery
    - Publish_GitHub_Wiki_Content

Generate_Wiki_Content

This is a metatask that runs the task (in order):

  • Create_Wiki_Output_Folder
  • Generate_Markdown_For_Public_Commands
  • Generate_External_Help_File_For_Public_Commands
  • Prepare_Markdown_FileNames_For_GitHub_Publish
  • Clean_Markdown_Of_Public_Commands
  • Generate_Markdown_For_DSC_Resources
  • Copy_Source_Wiki_Folder
  • Clean_WikiContent_For_GitHub_Publish

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

Generate_Markdown_For_DSC_Resources

This build task runs the command New-DscResourceWikiPage to build documentation for DSC resources.

See the command New-DscResourceWikiPage 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

  docs:
    - Generate_Conceptual_Help
    - Create_Wiki_Output_Folder
    - Generate_Markdown_For_DSC_Resources
    - Copy_Source_Wiki_Folder
    - Package_Wiki_Content

Generate_Wiki_Sidebar

This build task runs the command New-GitHubWikiSidebar (PlatyPS command) that will generate markdown for the module's public commands. See the command New-GitHubWikiSidebar for more information.

It is possible to pass:

  • DocOutputFolder (default is ./output/WikiContent)
  • DebugTask (default is $true)

They can be set either in parent scope, as an environment variable, or if passed as a parameter 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 all the needed tasks that generate markdown documentation. It must be run before Clean_Markdown_Metadata.

BuildWorkflow:
  '.':
    - build

  build:
    - Clean
    - Build_Module_ModuleBuilder
    - Build_NestedModules_ModuleBuilder
    - Create_changelog_release_output
    - Generate_Wiki_Content
    - Generate_Markdown_For_Public_Commands
    - Clean_Markdown_Of_Public_Commands
    - Generate_Wiki_Sidebar
    - Clean_Markdown_Metadata

  publish:
    - Publish_release_to_GitHub
    - publish_module_to_gallery
    - Publish_GitHub_Wiki_Content

Prepare_Markdown_FileNames_For_GitHub_Publish

Important

This task does not work in Windows PowerShell due to it not supporting unicode in filenames.

This build task will replace the hyphen in the markdown filenames with the unicode non-breaking hyphen. It can be controlled by parameter ReplaceHyphen in the task, which defaults to $true.

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_Markdown_For_Public_Commands
    - Prepare_Markdown_FileNames_For_GitHub_Publish

Publish_GitHub_Wiki_Content

This build task runs the command 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.

See the command Publish-WikiContent for more information.

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

It is also possible to enable debug output information for the task when it is run by adding this to the build configuration:

DscResource.DocGenerator:
  Publish_GitHub_Wiki_Content:
    Debug: true

Package_Wiki_Content

This build task runs the command Compress-Archive.

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 docs 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

  docs:
    - Generate_Conceptual_Help
    - Generate_Wiki_Content
    - Package_Wiki_Content