search

dsccommunity / AzureDevOpsDsc

This module contains DSC resources for deployment and configuration of initially Azure DevOps Services and later Azure DevOps Server.
MIT License
1 stars 5 forks source link

AzureDevOpsDsc: Wiki help and examples needs automatically generating #15

Closed SphenicPaul closed 3 years ago

SphenicPaul commented 3 years ago

Logging this issue off the back of the initial PR (#7) so it's logged and not missed...

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

With other DSC Community modules (e.g. SqlServerDsc), the Wiki help is generated from MOF schema definitions - Currently this module uses class-based resources and there is no current equivalent to generate this documentation.

There needs to be some functionality added to generate the Wiki.

SphenicPaul commented 3 years ago

Note that an issue has been raised in DscResource.DocGenerator project as the existing functionality currently doesn't support class-based, DSC resources.

Ensure that any fix also includes documentation relating to Examples based on class-based resources (original points raised in #11).

johlju commented 3 years ago

The build.yml should be updated with the following when fixing this issue (after issue https://github.com/dsccommunity/DscResource.DocGenerator/issues/51 has been resolved). It will make it possible to use markdown code in the comment-based help that will be used for the Wiki pages, but removed for the conceptual help.

####################################################
#      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)

Wiki page generation is probably not supported by DscResource.DocGenerator for class-based resource yet either.

johlju commented 3 years ago

The issue https://github.com/dsccommunity/DscResource.DocGenerator/issues/51 has been resolved and DscResource.DocGenerator can now generate conceptual help for class-based resource. But the issue https://github.com/dsccommunity/DscResource.DocGenerator/issues/52 is tracking that Wiki generation is not yet supported for class-based resources.

My plan is try to resolve https://github.com/dsccommunity/DscResource.DocGenerator/issues/52 on weekend in the near future.