From d62d14c03c788ebadfd6a3aebf01a8c6edd0c32b Mon Sep 17 00:00:00 2001 From: Johan Ljunggren Date: Thu, 18 Jul 2024 22:41:02 +0200 Subject: [PATCH] Automatic wiki documentation (#471) --- CHANGELOG.md | 5 +++ RequiredModules.psd1 | 4 +- Sampler/Templates/Build/build.yaml.template | 7 ++- Sampler/WikiSource/Home.md | 28 ++++++++++++ build.yaml | 49 ++++++++++++++++++++- 5 files changed, 86 insertions(+), 7 deletions(-) create mode 100644 Sampler/WikiSource/Home.md diff --git a/CHANGELOG.md b/CHANGELOG.md index fb19e78a..3f902048 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/RequiredModules.psd1 b/RequiredModules.psd1 index 15cefa21..0911c71f 100644 --- a/RequiredModules.psd1 +++ b/RequiredModules.psd1 @@ -23,6 +23,6 @@ 'DscResource.Test' = 'latest' 'DscResource.AnalyzerRules' = 'latest' xDscResourceDesigner = 'latest' - - PlatyPS = 'latest' + PlatyPS = 'latest' + 'DscResource.DocGenerator' = 'latest' } diff --git a/Sampler/Templates/Build/build.yaml.template b/Sampler/Templates/Build/build.yaml.template index 5626c34e..e7c4bf44 100644 --- a/Sampler/Templates/Build/build.yaml.template +++ b/Sampler/Templates/Build/build.yaml.template @@ -154,11 +154,10 @@ 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 "@ } @@ -166,11 +165,11 @@ BuildWorkflow: <% 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 # diff --git a/Sampler/WikiSource/Home.md b/Sampler/WikiSource/Home.md new file mode 100644 index 00000000..06049831 --- /dev/null +++ b/Sampler/WikiSource/Home.md @@ -0,0 +1,28 @@ +# Welcome to the Sampler wiki + +*Sampler v#.#.#* + +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). diff --git a/build.yaml b/build.yaml index f5d354df..0e226a58 100644 --- a/build.yaml +++ b/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: gaelcolas@synedgy.com 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