Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

AzureDevOpsDsc: Wiki help and examples needs automatically generating #15

Closed
SphenicPaul opened this issue Jan 24, 2021 · 3 comments · Fixed by #31
Closed

AzureDevOpsDsc: Wiki help and examples needs automatically generating #15

SphenicPaul opened this issue Jan 24, 2021 · 3 comments · Fixed by #31
Labels
enhancement The issue is an enhancement request.

Comments

@SphenicPaul
Copy link
Contributor

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.
@johlju johlju added enhancement The issue is an enhancement request. help wanted The issue is up for grabs for anyone in the community. labels Jan 24, 2021
@SphenicPaul SphenicPaul mentioned this issue Jan 28, 2021
Closed
@SphenicPaul
Copy link
Contributor Author

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

@SphenicPaul SphenicPaul changed the title AzureDevOpsDsc: Wiki help needs automatically generating AzureDevOpsDsc: Wiki help and examples needs automatically generating Jan 28, 2021
@johlju
Copy link
Member

johlju commented Jan 31, 2021 •
edited
Loading

The build.yml should be updated with the following when fixing this issue (after issue dsccommunity/DscResource.DocGenerator#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
Copy link
Member

johlju commented Feb 3, 2021

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

My plan is try to resolve dsccommunity/DscResource.DocGenerator#52 on weekend in the near future.

@johlju johlju added in progress The issue is being actively worked on by someone. and removed help wanted The issue is up for grabs for anyone in the community. labels Feb 8, 2021
@johlju johlju mentioned this issue Feb 8, 2021
Merged
9 tasks
johlju added a commit that referenced this issue Feb 11, 2021
@johlju
AzureDevOpsDsc: Support publish wiki documentation (#31)
5cd23a0 
- AzureDevOpsDsc
  - Added pipeline support for publish markdown content to the GitHub repository
    wiki ([issue #15](#15)).
    This will publish the markdown documentation that is generated bu the
    build pipeline.
  - Added new source folder `WikiSource`. Every markdown file in the folder
    `WikiSource` will be published to the GitHub repository wiki. The markdown
    file `Home.md` will be updated with the correct module version on each
    publish to gallery (including preview).
  - Updated pipeline file `RequiredModules.ps1` to latest pipeline pattern.
  - Updated pipeline file `build.yaml` to latest pipeline pattern.
- AzDevOpsProject
  - Added description to the comment-based help.
  - Added a validate set to the parameter `SourceControlType` to (for now)
    limit the parameter to the values `Git` and `Tfvc`.
  - Update comment-based help to remove text which the valid values are
    since that is now add automatically to the documentation (conceptual
    help and wiki documentation).
@johlju johlju removed the in progress The issue is being actively worked on by someone. label Feb 11, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement The issue is an enhancement request.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

AzureDevOpsDsc: Support publish wiki documentation johlju/AzureDevOpsDsc
2 participants
@johlju @SphenicPaul