diff --git a/CHANGELOG.md b/CHANGELOG.md index 2ac12ff..303c69d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Check for a prefixed and non-prefixed class names [issue #132](https://github.com/dsccommunity/DscResource.DocGenerator/issues/132). - `azure-pipelines` - Pin gitversion to V5. +- Update README with the tasks that were not documented. +- `Generate_Wiki_Content` + - Change the order of the tasks to avoid getting and exception when + `source/WikiSource` contain additional markdown files that are copied + to `output/WikiContent`. ## [0.12.4] - 2024-06-03 diff --git a/README.md b/README.md index 4e7f923..970021e 100644 --- a/README.md +++ b/README.md @@ -136,6 +136,42 @@ BuildWorkflow: - Publish_GitHub_Wiki_Content ``` +### `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](https://github.com/gaelcolas/Sampler) project. + +```yaml +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`. @@ -304,22 +340,14 @@ BuildWorkflow: ### `Generate_Wiki_Content` -This build task runs the command `New-DscResourceWikiPage` to build -documentation for DSC resources. +This is a metatask that runs the task (in order): -The task will also 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. - -See the command `New-DscResourceWikiPage` for more information. +- `Create_Wiki_Output_Folder` +- `Generate_Markdown_For_Public_Commands` +- `Generate_External_Help_File_For_Public_Commands` +- `Clean_Markdown_Of_Public_Commands` +- `Generate_Markdown_For_DSC_Resources` +- `Copy_Source_Wiki_Folder` Below is an example how the build task can be used when a repository is based on the [Sampler](https://github.com/gaelcolas/Sampler) project. @@ -337,6 +365,29 @@ BuildWorkflow: - 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](https://github.com/gaelcolas/Sampler) project. + +```yaml +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 diff --git a/source/tasks/Generate_Wiki_Content.build.ps1 b/source/tasks/Generate_Wiki_Content.build.ps1 index bfea2c4..e6cb24c 100644 --- a/source/tasks/Generate_Wiki_Content.build.ps1 +++ b/source/tasks/Generate_Wiki_Content.build.ps1 @@ -84,4 +84,4 @@ param $BuildInfo = (property BuildInfo @{ }) ) -Task Generate_Wiki_Content Create_Wiki_Output_Folder, Copy_Source_Wiki_Folder, Generate_Markdown_For_DSC_Resources, Generate_Markdown_For_Public_Commands, Generate_External_Help_File_For_Public_Commands, Clean_Markdown_Of_Public_Commands +Task Generate_Wiki_Content Create_Wiki_Output_Folder, Generate_Markdown_For_Public_Commands, Generate_External_Help_File_For_Public_Commands, Clean_Markdown_Of_Public_Commands, Generate_Markdown_For_DSC_Resources, Copy_Source_Wiki_Folder