Add support for Auto Documentation - Fixes #677 #728

PlagueHO · 2021-09-11T02:51:23Z

Pull Request (PR) description

This PR will add support for automatic documentation and Wiki generation.

This Pull Request (PR) fixes the following issues

Fixes Add Automated Documentation Generation #677

Task list

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).
Resource documentation added/updated in README.md.
Resource parameter descriptions added/updated in README.md, schema.mof
and comment-based help.
Comment-based help added/updated.
Localization strings added/updated in all localization files as appropriate.
Examples appropriately added/updated.
Unit tests added/updated. See DSC Community Testing Guidelines.
Integration tests added/updated (where possible). See DSC Community Testing Guidelines.
New/changed code adheres to DSC Community Style Guidelines.

This change is

… module

codecov · 2021-09-11T06:30:31Z

Codecov Report

Merging #728 (a333831) into main (475885c) will decrease coverage by 0%.
The diff coverage is 100%.

❗ Current head a333831 differs from pull request most recent head cbf6975. Consider uploading reports for the commit cbf6975 to get more accurate results

@@         Coverage Diff         @@
##           main   #728   +/-   ##
===================================
- Coverage    72%    72%   -1%     
===================================
  Files        30     30           
  Lines      4427   4427           
===================================
- Hits       3213   3199   -14     
- Misses     1214   1228   +14

Impacted Files	Coverage Δ
...sources/DSC_xDSCWebService/DSC_xDSCWebService.psm1	`88% <ø> (ø)`
...sources/DSC_xGroupResource/DSC_xGroupResource.psm1	`70% <ø> (ø)`
...sionConfiguration/DSC_xPSSessionConfiguration.psm1	`0% <ø> (ø)`
...ces/DSC_xPackageResource/DSC_xPackageResource.psm1	`76% <ø> (-4%)`	⬇️
...urces/DSC_xScriptResource/DSC_xScriptResource.psm1	`100% <ø> (ø)`
...ces/DSC_xServiceResource/DSC_xServiceResource.psm1	`93% <ø> (ø)`
...Resources/DSC_xUserResource/DSC_xUserResource.psm1	`53% <ø> (ø)`
...urces/DSC_xWindowsFeature/DSC_xWindowsFeature.psm1	`86% <ø> (ø)`
.../xWindowsFeatureSet/xWindowsFeatureSet.schema.psm1	`0% <ø> (ø)`
...xEnvironmentResource/DSC_xEnvironmentResource.psm1	`91% <100%> (ø)`
... and 1 more

PlagueHO · 2021-09-11T21:30:15Z

Hi @johlju - would you mind reviewing this when you get time? Thanks!

johlju

Reviewed 127 of 136 files at r1, 9 of 9 files at r2, all commit messages.
Reviewable status: all files reviewed, 5 unresolved discussions (waiting on @PlagueHO)

a discussion (no related file):
Should add a WikiSource folder, under ./source, then add a Home.md, like this: https://github.com/dsccommunity/FileSystemDsc/blob/main/source/WikiSource/Home.md.

There is a placeholder in this file that will automatically update to the semantic version during build (and then published).

README.md, line 19 at r2 (raw file):

against that module

Maybe "against this module"?

README.md, line 47 at r2 (raw file):

## Resources

In the future: Seeing this, we should really try to add this ToC-list to the Home.md automatically based on the resource's README.md 🤔 Then a contributor does not need to update this README.md for new resource. But non-blocking as that is a big thing to create. I have created a new issue for that in DocGenerator.

.vscode/settings.json, line 11 at r2 (raw file):

"powershell.codeFormatting.pipelineIndentationStyle": "IncreaseIndentationAfterEveryPipeline",

I usually change this to '...FirstPipeline' otherwise we have to change all code again in all repos. I have (now) added and issue to fix this in Sampler.

source/DSCResources/DSC_xPackageResource/en-US/DSC_xPackageResource.schema.mfl, line 1 at r2 (raw file):

xMsiPackage

THis is not xMsiPackage, but xPackage?

source/Examples/Resources/xDscWebService/5-xDscWebService_RegistrationWithSecurityBestPractices_Config.ps1, line 81 at r2 (raw file):

Import-DSCResource

I think this should still be Import-DscResource (lowercase 'sc' in 'Dsc'). Throughout.

johlju · 2021-09-18T15:46:08Z

@PlagueHO just minor things! Awesome work on this, I know how long it takes to do a PR like this 😄

PlagueHO

Reviewable status: all files reviewed, 4 unresolved discussions (waiting on @johlju)

a discussion (no related file):