Automatic wiki documentation (#471)

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Added extensions.json for vscode
+- Automatic wiki documentation for public commands.
 
 ### Changed
 
@@ -28,6 +29,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Switch to build worker `windows-latest` for the build phase of the pipeline
   due to a issue using `Publish-Module` on the latest updated build worker in
   Azure Pipelines.
+- Public command documentation has been moved from README.md to the GitHub
+  repository Wiki.
+- Update order of deploy tasks for the Plaster templates to make it easier
+  to re-run a deploy phase when a GitHub token has expired.
 
 ### Fixed
 

RequiredModules.psd1

@@ -23,6 +23,6 @@
     'DscResource.Test'          = 'latest'
     'DscResource.AnalyzerRules' = 'latest'
     xDscResourceDesigner        = 'latest'
-
-    PlatyPS = 'latest'
+    PlatyPS                     = 'latest'
+    'DscResource.DocGenerator'  = 'latest'
 }

Sampler/Templates/Build/build.yaml.template

@@ -154,23 +154,22 @@ BuildWorkflow:
     #- Merge_CodeCoverage_Files
 
   publish:
-    - publish_module_to_gallery
 <%
     if($PLASTER_PARAM_ModuleType -in @('dsccommunity', 'CompleteSample') -or $PLASTER_PARAM_Features -Contains ('All')) {
 @"
-    - Publish_Release_To_GitHub
+    - Publish_Release_To_GitHub # Runs first, if token is expired it will fail early
     - Publish_GitHub_Wiki_Content
 "@
     }
 %>
 <%
     if($PLASTER_PARAM_UseGitHub -eq 'true' -or $PLASTER_PARAM_Features -Contains ('All') -or $PLASTER_PARAM_Features -Contains ('GitHub')) {
 @"
-    - Publish_Release_To_GitHub
+    - Publish_Release_To_GitHub # Runs first, if token is expired it will fail early
 "@
     }
 %>
-
+    - publish_module_to_gallery
 
 ####################################################
 #       PESTER  Configuration                      #

Sampler/WikiSource/Home.md

@@ -0,0 +1,28 @@
+# Welcome to the Sampler wiki
+
+<sup>*Sampler v#.#.#*</sup>
+
+Here you will find all the information you need to make use of Sampler.
+
+Please leave comments, feature requests, and bug reports for this module in
+the [issues section](https://github.com/gaelcolas/Sampler/issues)
+for this repository.
+
+## Getting started
+
+To get started either:
+
+- Install from the PowerShell Gallery using PowerShellGet by running the
+  following command:
+
+```powershell
+Install-Module -Name Sampler -Repository PSGallery
+```
+
+## Prerequisites
+
+- PowerShell 5.1 or higher
+
+## Change log
+
+A full list of changes in each version can be found in the [change log](https://github.com/gaelcolas/Sampler/blob/main/CHANGELOG.md).

build.yaml

@@ -128,8 +128,22 @@ BuildWorkflow:
     - Build_NestedModules_ModuleBuilder
     - Create_changelog_release_output
 
+  docs:
+    # The meta task Generate_Wiki_Content is not used so that Linux and macOS is supported
+    # - Generate_Conceptual_Help # Used for DSC resources
+    - Create_Wiki_Output_Folder
+    - Copy_Source_Wiki_Folder
+    # - Generate_Markdown_For_DSC_Resources # Used for DSC resources
+    - Generate_Markdown_For_Public_Commands
+    - Generate_External_Help_File_For_Public_Commands
+    - Clean_Markdown_Of_Public_Commands
+    - Generate_Wiki_Sidebar
+    - Clean_Markdown_Metadata
+    - Package_Wiki_Content
+
   pack:
     - build
+    - docs
     - package_module_nupkg
 
   hqrmtest:
@@ -146,9 +160,10 @@ BuildWorkflow:
     - Merge_CodeCoverage_Files
 
   publish:
+    - Publish_release_to_GitHub # Runs first, if token is expired it will fail early
     #- publish_nupkg_to_gallery  # Deploy using Nuget
     - publish_module_to_gallery # Deploy using cmdlet Publish-Module
-    - Publish_release_to_GitHub
+    - Publish_GitHub_Wiki_Content
 
 # Import ModuleBuilder tasks from a specific PowerShell module using the build
 # task's alias. Wildcard * can be used to specify all tasks that has a similar
@@ -159,6 +174,8 @@ ModuleBuildTasks:
     - '*.ib.tasks'
   DscResource.Test:
     - 'Task.*'
+  DscResource.DocGenerator:
+    - 'Task.*'
 
 # Invoke-Build Header to be used to 'decorate' the terminal output of the tasks.
 TaskHeader: |
@@ -175,6 +192,8 @@ TaskHeader: |
 GitHubConfig:
   GitHubFilesToAdd:
     - 'CHANGELOG.md'
+  ReleaseAssets:
+    - output/WikiContent.zip
   GitHubConfigUserName: gaelcolas
   GitHubConfigUserEmail: [email protected]
   UpdateChangelogOnPrerelease: false
@@ -185,3 +204,31 @@ GitHubConfig:
   #RemoveProgramFiles: true
   #RemoveWindows: false
   #SetSystemDefault: false
+
+####################################################
+#      DscResource.DocGenerator Configuration      #
+####################################################
+DscResource.DocGenerator:
+  # Generate_Conceptual_Help:
+  #   MarkdownCodeRegularExpression:
+  #     - '\`(.+?)\`' # Match inline code-block
+  #     - '\\(\\)' # Match escaped backslash
+  #     - '\[[^\[]+\]\((.+?)\)' # Match markdown URL
+  #     - '_(.+?)_' # Match Italic (underscore)
+  #     - '\*\*(.+?)\*\*' # Match bold
+  #     - '\*(.+?)\*' # Match Italic (asterisk)
+  Publish_GitHub_Wiki_Content:
+    Debug: false
+  Generate_Wiki_Content:
+    # MofResourceMetadata:
+    #   Type: MofResource
+    #   Category: Resources
+    # ClassResourceMetadata:
+    #   Type: ClassResource
+    #   Category: Resources
+    # CompositeResourceMetadata:
+    #   Type: CompositeResource
+    #   Category: Resources
+  Generate_Wiki_Sidebar:
+     Debug: false
+     AlwaysOverwrite: true