Make `Generate_Wiki_Content` a metatask

dan-hughes commented 6 months ago

Pull Request (PR) description

Change Generate_Wiki_Content to a metatask, split existing Generate_Wiki_Content into individual subtasks. Update tests for new tasks.

This Pull Request (PR) fixes the following issues

Fixes #135

Task list

[x] Added an entry to the change log under the Unreleased section of the file CHANGELOG.md. Entry should say what was changed and how that affects users (if applicable), and reference the issue being resolved (if applicable).
[ ] Documentation added/updated in README.md.
[ ] Comment-based help added/updated.
[ ] Localization strings added/updated in all localization files as appropriate.
[ ] Examples appropriately added/updated.
[x] Unit tests added/updated. See DSC Community Testing Guidelines.
[ ] Integration tests added/updated (where possible). See DSC Community Testing Guidelines.
[x] New/changed code adheres to DSC Community Style Guidelines.

This change is

dan-hughes commented 6 months ago

@johlju, for review.

I have an issue I do not understand how to resolve. The metatask does not know how to resolve/find the tasks, what am I doing wrong?

Changelog and Docs are incoming.

codecov[bot] commented 6 months ago

Codecov Report

Attention: Patch coverage is 85.71429% with 8 lines in your changes are missing coverage. Please review.

Project coverage is 95%. Comparing base (589ccbd) to head (d30ceb7).

Additional details and impacted files

[![Impacted file tree graph](https://app.codecov.io/gh/dsccommunity/DscResource.DocGenerator/pull/145/graphs/tree.svg?width=650&height=150&src=pr&token=bSbVj9muPO&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dsccommunity)](https://app.codecov.io/gh/dsccommunity/DscResource.DocGenerator/pull/145?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dsccommunity) ```diff @@ Coverage Diff @@ ## main #145 +/- ## =================================== - Coverage 96% 95% -1% =================================== Files 59 65 +6 Lines 1198 1234 +36 =================================== + Hits 1151 1174 +23 - Misses 47 60 +13 ``` | [Files](https://app.codecov.io/gh/dsccommunity/DscResource.DocGenerator/pull/145?dropdown=coverage&src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dsccommunity) | Coverage Δ | | |---|---|---| | [source/Private/Task.Copy\_Source\_Wiki\_Folder.ps1](https://app.codecov.io/gh/dsccommunity/DscResource.DocGenerator/pull/145?src=pr&el=tree&filepath=source%2FPrivate%2FTask.Copy_Source_Wiki_Folder.ps1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dsccommunity#diff-c291cmNlL1ByaXZhdGUvVGFzay5Db3B5X1NvdXJjZV9XaWtpX0ZvbGRlci5wczE=) | `100% <100%> (ø)` | | | [source/Private/Task.Create\_Wiki\_Output\_Folder.ps1](https://app.codecov.io/gh/dsccommunity/DscResource.DocGenerator/pull/145?src=pr&el=tree&filepath=source%2FPrivate%2FTask.Create_Wiki_Output_Folder.ps1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dsccommunity#diff-c291cmNlL1ByaXZhdGUvVGFzay5DcmVhdGVfV2lraV9PdXRwdXRfRm9sZGVyLnBzMQ==) | `100% <100%> (ø)` | | | [...ivate/Task.Generate\_Markdown\_For\_DSC\_Resources.ps1](https://app.codecov.io/gh/dsccommunity/DscResource.DocGenerator/pull/145?src=pr&el=tree&filepath=source%2FPrivate%2FTask.Generate_Markdown_For_DSC_Resources.ps1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dsccommunity#diff-c291cmNlL1ByaXZhdGUvVGFzay5HZW5lcmF0ZV9NYXJrZG93bl9Gb3JfRFNDX1Jlc291cmNlcy5wczE=) | `100% <100%> (ø)` | | | [source/tasks/Copy\_Source\_Wiki\_Folder.build.ps1](https://app.codecov.io/gh/dsccommunity/DscResource.DocGenerator/pull/145?src=pr&el=tree&filepath=source%2Ftasks%2FCopy_Source_Wiki_Folder.build.ps1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dsccommunity#diff-c291cmNlL3Rhc2tzL0NvcHlfU291cmNlX1dpa2lfRm9sZGVyLmJ1aWxkLnBzMQ==) | `91% <91%> (ø)` | | | [source/tasks/Create\_Wiki\_Output\_Folder.build.ps1](https://app.codecov.io/gh/dsccommunity/DscResource.DocGenerator/pull/145?src=pr&el=tree&filepath=source%2Ftasks%2FCreate_Wiki_Output_Folder.build.ps1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dsccommunity#diff-c291cmNlL3Rhc2tzL0NyZWF0ZV9XaWtpX091dHB1dF9Gb2xkZXIuYnVpbGQucHMx) | `85% <85%> (ø)` | | | [...asks/Generate\_Markdown\_For\_DSC\_Resources.build.ps1](https://app.codecov.io/gh/dsccommunity/DscResource.DocGenerator/pull/145?src=pr&el=tree&filepath=source%2Ftasks%2FGenerate_Markdown_For_DSC_Resources.build.ps1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dsccommunity#diff-c291cmNlL3Rhc2tzL0dlbmVyYXRlX01hcmtkb3duX0Zvcl9EU0NfUmVzb3VyY2VzLmJ1aWxkLnBzMQ==) | `85% <85%> (ø)` | | | [source/tasks/Generate\_Wiki\_Content.build.ps1](https://app.codecov.io/gh/dsccommunity/DscResource.DocGenerator/pull/145?src=pr&el=tree&filepath=source%2Ftasks%2FGenerate_Wiki_Content.build.ps1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dsccommunity#diff-c291cmNlL3Rhc2tzL0dlbmVyYXRlX1dpa2lfQ29udGVudC5idWlsZC5wczE=) | `0% <0%> (-90%)` | :arrow_down: |

johlju commented 6 months ago

Hmm. I will take a look, but might not have time today, and maybe not tomorrow either. But will be back as soon as possible. 🙂

johlju commented 6 months ago

Building the module using this PR it seems to work.

Running ./build.ps1 ? shows the metatask and that it will run the other tasks. Running ./build.ps1 -Task Generate_Wiki_Content works too. So for some reason the tests don't find it.

johlju commented 6 months ago

It is because in the tests we just point out one of the needed script files, e.g.

invoke-build -Task Generate_Wiki_Content -File .\output\DscResource.DocGenerator\0.13.0\tasks\Generate_Wiki_Content.build.ps1

It returns the same error:

ERROR: Task 'Generate_Wiki_Content': Missing task 'Create_Wiki_Output_Folder'.
At C:\source\DscResource.DocGenerator\output\DscResource.DocGenerator\0.13.0\tasks\Generate_Wiki_Content.build.ps1:87 char:1
+ Task Generate_Wiki_Content Create_Wiki_Output_Folder, Copy_Source_Wik …
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Build ABORTED C:\source\DscResource.DocGenerator\output\DscResource.DocGenerator\0.13.0\tasks\Generate_Wiki_Content.build.ps1. 0 tasks, 1 errors, 0 warnings 00:00:00.0277892
Invoke-Build.ps1: Task 'Generate_Wiki_Content': Missing task 'Create_Wiki_Output_Folder'.
At C:\source\DscResource.DocGenerator\output\DscResource.DocGenerator\0.13.0\tasks\Generate_Wiki_Content.build.ps1:87 char:1
+ Task Generate_Wiki_Content Create_Wiki_Output_Folder, Copy_Source_Wik …
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

johlju commented 6 months ago

TLDR; I think we skip testing the metatask. 🙂

I have tried building a temp script file that dot-sources all the required task script files, but it errors out on not having the parameters we pass in the test.

    [-] Should run the build task without throwing 44ms
      Expected no exception to be thrown, but an exception "A parameter cannot be found that matches parameter name 'ProjectName'." was thrown from C:\source\DscResource.DocGenerator\tests\unit\tasks\Generate_Wiki_Content.build.Tests.ps1:55 char:25
          +              ) -Verbose @taskParameters
          +                         ~~~~~~~~~~~~~~~.
      56:         } | Should -Not -Throw
      at <ScriptBlock>, C:\source\DscResource.DocGenerator\tests\unit\tasks\Generate_Wiki_Content.build.Tests.ps1: line 44

So only way to make this work is to dynamically build a task script file with all the required tasks in it during testing, but that is not worth the effort so I suggest we skip testing the metatask. I think Invoke-Build assumes there should be only on script file with all tasks in it, the Sampler build script handles this that way it allows us to split up the tasks in separate files . Maybe the pipeline in this module should actually build the tasks script files into a single file in the built module. Then there would for example only be one script file that holds all parameters and they are not duplicate though out the task script files. 🤔 We would then just test one single script file in each test file. That it can be a future improvement for the project Sampler, it is a big undertaking fixing that - sounds like a "bad weather" project. 😄

dan-hughes commented 6 months ago

Done.

johlju commented 6 months ago

@dan-hughes Impressive work! Awesome! Thank you! 🙇‍♂️

dsccommunity / DscResource.DocGenerator