search

gaelcolas / Sampler

Module template with build pipeline and examples, including DSC elements.
MIT License
171 stars 42 forks source link

How to support PlatyPS and `Get-Help` seeing comment-based help #451

Closed johlju closed 10 months ago

johlju commented 11 months ago

I’m working on (opinionated) build tasks (https://github.com/dsccommunity/DscResource.DocGenerator/pull/133) that will generate GitHub wiki documentation for the public commands of a module using PlatyPS. These tasks are different than those in Sampler which are more meant to support different locales and adds documentation to source. The ones in *.DocGenerator will generate documentation at build time and make documentation that the pipeline deploy to the GitHub repository wiki, same as what is done for the DSC resource documentation today.

Anyway, the problem I have is that how ModuleBuilder works currently and how we add comment-based help before the function-statement according to the style-guideline, the command in PlatyPS does not recognize the comment-based help since ModuleBuilder have no way of prefixing each command script file with a blank line. Since it adds no blank line between the previous function and the next functions comment-based help PlatyPS cannot see the help text. Neither does the command Get-Help.

The solution is to add a blank line between the previous function and the next function. Another solution would be to add the comment-based help inside the function-block, but that would mean we would have to change the style guideline, and all existing code would not be complaint.

So, question. What would be the best approach?

  1. Add a blank line at the top of each public command script file in the Public-folder, then add a QA test that verifies that all script files has this blank line.
  2. Add a new task Edit_Built_Module that can optionally be added to the build pipeline that modifies the built module, in this case by adding a new line between each function (and keeping the source files as-is).
  3. Modify Sampler to do list item 2 in the a existing Sampler’s Build_Module_ModuleBuilder task.
  4. Another option would be to modify ModuleBuilder to support a optional “script file prefix”, but not sure it will be accepted. I asked in the issue https://github.com/PoshCode/ModuleBuilder/issues/126.
johlju commented 10 months ago

Option 2 and 3 won't work as it will break code coverage between built module (that tests are run against) and the source files. Option 4 is the best approach, it will make code coverage work too. I'm waiting for the PR https://github.com/PoshCode/ModuleBuilder/pull/127 to be reviewed and merged, this will solve this issue. In the mean time it can be worked around by using option 1 and implement this QA test: https://github.com/dsccommunity/SqlServerDsc/blob/68c9b1078ba3dee2aeed49ebc129fa799d4b80b7/tests/QA/module.tests.ps1#L226-L243

johlju commented 10 months ago

ModuleBuilder is now released with the above fix.