New-DscResourcePowerShellHelp: Add functionality to generate contextual help from class-based, DSC resources

[SphenicPaul]

Details of the scenario you tried and the problem that is occurring

The New-DscResourcePowerShellHelp function (and Generate_Conceptual_Help task) contextual help doesn't currently seem to parse class-based, DSC resources.

Steps to reproduce the problem

Build a DscCommunity build with class based resources (e.g. AzureDevOpsDsc).

Expected behavior

Should identify class-based, DSC resources and generate contextual help.

Current behavior

Generates nothing. Currently only generating for MOF-based resources.

Suggested solution to the issue

Implement functionality in New-DscResourcePowerShellHelp function to identify and generate help from class-based DSC resources.

Possibly use [DscResource()], class attribute and/or Classes, subdirectory to identify. Possibly add other class attributes to detail descriptions/information to be used as part of the contextual help?

The operating system the target node is running

n/a

Version and build of PowerShell the target node is running

PSVersion 5.1.19041.610
PSEdition Desktop
PSCompatibleVersions {1.0, 2.0, 3.0, 4.0...}
BuildVersion 10.0.19041.610
CLRVersion 4.0.30319.42000
WSManStackVersion 3.0
PSRemotingProtocolVersion 2.3
SerializationVersion 1.1.0.1

Version of the module that was used

v0.7.2

[johlju]

@SphenicPaul I could make this a weekend project. I get to learn some AST around classes.

[johlju]

@SphenicPaul Working on this, but got a design question.

For MOF-resources there is a README.md file for each MOF-resource that is used for the .DESCRIPTION part of the conceptual help. This README.md is for MOF-resource located in the resource folder, e.g. https://github.com/dsccommunity/SqlServerDsc/blob/main/source/DSCResources/DSC_SqlAG/README.md.

For class-based resource where should we put these README.md files, and should they be named as the resource name, e.g. AzureDevOpsProject.md? Should we have a source/docs folder where these are? Putting them in Classes folder seems wrong (if ModuleBuilder even likes that).

Example of how the README.md is generated:

.NAME
    SqlAG

.DESCRIPTION
    The `SqlAG` DSC resource is used to create, remove, and update an Always On
    Availability Group. It will also manage the Availability Group replica on the
    specified node.

    ## Requirements

    * Target machine must be running Windows Server 2012 or later.
    * Target machine must be running SQL Server Database Engine 2012 or later.
    * 'NT SERVICE\ClusSvc' or 'NT AUTHORITY\SYSTEM' must have the 'Connect SQL',
      'Alter Any Availability Group', and 'View Server State' permissions.

    ## Known issues

    All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlAG).

[johlju]

@SphenicPaul Maybe we shouldn't use a markdown file at all. Should we just use the comment-based that is part of the class help for this? For now I work on that assumption that we just use the comment-based help.

[SphenicPaul]

I think using the comment-based help makes sense - It removes the requirement for an extra file and there isn't the additional subfolder within the Classes directory structure for it to sit in.

[johlju]

I have this working now. Sending in PR shortly. There is no native support for comment-based help for PowerShell classes through AST (only for functions and scriptblocks). So I have to cheat and load the source file as script file (which become a script block - single resource in single file = single script block ) and then use the AST's method GetHelpContent().

If there is native support for comment-based help for classes in future we have to revisit this.

[johlju]

@SphenicPaul if you wouldn't mind I would love a review on PR #53 if you have time. 🙂