Add support for Auto Documentation - Fixes #677 (#728)

.gitattributes

@@ -2,3 +2,9 @@
 # Set default behavior to automatically normalize line endings.
 ###############################################################################
 * text eol=crlf
+
+# Ensure any exe files are treated as binary
+*.exe binary
+*.jpg binary
+*.xl* binary
+*.pfx binary

.gitignore

@@ -2,8 +2,8 @@
 *.user
 *.coverage
 .vs
+.vscode
 .psproj
 .sln
 markdownissues.txt
-TestResults.xml
 output/

.vscode/analyzersettings.psd1

@@ -1,10 +1,6 @@
 @{
-    <#
-        For the custom rules to work, the DscResource.Tests repo must be
-        cloned. It is automatically clone as soon as any unit or
-        integration tests are run.
-    #>
-    CustomRulePath = '.\DSCResource.Tests\DscResource.AnalyzerRules'
+    CustomRulePath      = '.\output\RequiredModules\DscResource.AnalyzerRules'
+    includeDefaultRules = $true
 
     IncludeRules   = @(
         # DSC Resource Kit style guideline rules.
@@ -43,11 +39,6 @@
         'PSUseDeclaredVarsMoreThanAssignments',
         'PSUsePSCredentialType',
 
-        <#
-            This is to test all the DSC Resource Kit custom rules.
-            The name of the function-blocks of each custom rule start
-            with 'Measure*'.
-        #>
         'Measure-*'
     )
 }

.vscode/settings.json

@@ -8,6 +8,7 @@
     "powershell.codeFormatting.whitespaceAroundOperator": true,
     "powershell.codeFormatting.whitespaceAfterSeparator": true,
     "powershell.codeFormatting.ignoreOneLineBlock": false,
+    "powershell.codeFormatting.pipelineIndentationStyle": "IncreaseIndentationForFirstPipeline",
     "powershell.codeFormatting.preset": "Custom",
     "files.trimTrailingWhitespace": true,
     "files.insertFinalNewline": true,

CHANGELOG.md

@@ -30,6 +30,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - Improved integration test reliability by resetting the DSC LCM
       before executing each test using the `Reset-DscLcm`
       function - Fixes [Issue #686](https://github.com/dsccommunity/xPSDesiredStateConfiguration/issues/686).
+  - Added build task `Generate_Conceptual_Help` to generate conceptual help
+    for the DSC resource - Fixes [Issue #677](https://github.com/dsccommunity/xPSDesiredStateConfiguration/issues/677).
+  - Added build task `Generate_Wiki_Content` to generate the wiki content
+    that can be used to update the GitHub Wiki - Fixes [Issue #677](https://github.com/dsccommunity/xPSDesiredStateConfiguration/issues/677).
 - xDSCWebService:
   - Moved strings into localization file - Fixes [Issue #622](https://github.com/dsccommunity/xPSDesiredStateConfiguration/issues/622).
   - Corrected case of `CertificateThumbPrint` to `CertificateThumbprint`.
@@ -38,6 +42,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated build to use `Sampler.GitHubTasks` - Fixes [Issue #711](https://github.com/dsccommunity/xPSDesiredStateConfiguration/issues/711).
 - Added support for publishing code coverage to `CodeCov.io` and
   Azure Pipelines - Fixes [Issue #711](https://github.com/dsccommunity/xPSDesiredStateConfiguration/issues/711).
+- Updated vmImage used for build stage of CI to use `Windows-2019` to resolve
+  issues with Wiki Generation of `xUploadFile` composite resource on Linux agents.
 
 ## [9.1.0] - 2020-02-19
 

CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# Contributing
+
+Please check out common DSC Community [contributing guidelines](https://dsccommunity.org/guidelines/contributing).
+
+## Running the Tests
+
+If want to know how to run this module's tests you can look at
+the [Testing Guidelines](https://dsccommunity.org/guidelines/testing-guidelines/#running-tests).

RequiredModules.psd1

@@ -13,9 +13,11 @@
     ModuleBuilder               = 'latest'
     ChangelogManagement         = 'latest'
     Sampler                     = 'latest'
+    MarkdownLinkCheck           = 'latest'
     'Sampler.GitHubTasks'       = 'latest'
     'DscResource.Test'          = 'latest'
     'DscResource.AnalyzerRules' = 'latest'
+    'DscResource.DocGenerator'  = 'latest'
     'DscResource.Common'        = 'latest'
     xDscResourceDesigner        = 'latest'
     NetworkingDsc               = '7.4.0.0'

azure-pipelines.yml

@@ -24,7 +24,7 @@ stages:
       - job: Package_Module
         displayName: 'Package Module'
         pool:
-          vmImage: 'ubuntu 16.04'
+          vmImage: 'windows-2019'
         steps:
           - task: GitVersion@5
             name: gitversion
@@ -123,7 +123,7 @@ stages:
         displayName: 'Publish Code Coverage'
         dependsOn: Test_Unit_2016
         pool:
-          vmImage: 'ubuntu 16.04'
+          vmImage: 'ubuntu-16.04'
         timeoutInMinutes: 0
         steps:
           - task: DownloadPipelineArtifact@2
@@ -269,7 +269,7 @@ stages:
       - job: Deploy_Module
         displayName: 'Deploy Module'
         pool:
-          vmImage: 'ubuntu 16.04'
+          vmImage: 'ubuntu-16.04'
         steps:
           - task: DownloadPipelineArtifact@2
             displayName: 'Download Pipeline Artifact'

build.ps1

@@ -18,7 +18,7 @@ param
     [validateScript(
         { Test-Path -Path $_ }
     )]
-    $BuildConfig = './build.yaml',
+    $BuildConfig,
 
     [Parameter()]
     # A Specific folder to build the artefact into.
@@ -35,22 +35,34 @@ param
     [Parameter()]
     $RequiredModulesDirectory = $(Join-Path 'output' 'RequiredModules'),
 
+    [Parameter()]
+    [object[]]
+    $PesterScript,
+
     # Filter which tags to run when invoking Pester tests
     # This is used in the Invoke-Pester.pester.build.ps1 tasks
     [Parameter()]
     [string[]]
     $PesterTag,
 
-    [Parameter()]
-    [string[]]
-    $PesterScript,
-
     # Filter which tags to exclude when invoking Pester tests
     # This is used in the Invoke-Pester.pester.build.ps1 tasks
     [Parameter()]
     [string[]]
     $PesterExcludeTag,
 
+    # Filter which tags to run when invoking DSC Resource tests
+    # This is used in the DscResource.Test.build.ps1 tasks
+    [Parameter()]
+    [string[]]
+    $DscTestTag,
+
+    # Filter which tags to exclude when invoking DSC Resource tests
+    # This is used in the DscResource.Test.build.ps1 tasks
+    [Parameter()]
+    [string[]]
+    $DscTestExcludeTag,
+
     [Parameter()]
     [Alias('bootstrap')]
     [switch]$ResolveDependency,
@@ -210,6 +222,22 @@ process
 
 Begin
 {
+    # Find build config if not specified
+    if (-not $BuildConfig) {
+        $config = Get-ChildItem -Path "$PSScriptRoot\*" -Include 'build.y*ml', 'build.psd1', 'build.json*' -ErrorAction:Ignore
+        if (-not $config -or ($config -is [array] -and $config.Length -le 0)) {
+            throw "No build configuration found. Specify path via -BuildConfig"
+        }
+        elseif ($config -is [array]) {
+            if ($config.Length -gt 1) {
+                throw "More than one build configuration found. Specify which one to use via -BuildConfig"
+            }
+            $BuildConfig = $config[0]
+        }
+        else {
+            $BuildConfig = $config
+        }
+    }
     # Bootstrapping the environment before using Invoke-Build as task runner
 
     if ($MyInvocation.ScriptName -notLike '*Invoke-Build.ps1')
@@ -308,7 +336,7 @@ Begin
         # If BuildConfig is a Yaml file, bootstrap powershell-yaml via ResolveDependency
         if ($BuildConfig -match '\.[yaml|yml]$')
         {
-            $ResolveDependencyParams.add('WithYaml', $true)
+            $ResolveDependencyParams.add('WithYaml', $True)
         }
 
         $ResolveDependencyAvailableParams = (Get-Command -Name '.\Resolve-Dependency.ps1').parameters.keys

build.yaml

@@ -34,6 +34,8 @@ BuildWorkflow:
     - Build_Module_ModuleBuilder
     - Build_NestedModules_ModuleBuilder
     - Create_changelog_release_output
+    - Generate_Conceptual_Help
+    - Generate_Wiki_Content
 
   pack:
     - build
@@ -87,6 +89,8 @@ ModuleBuildTasks:
     - '*.build.Sampler.ib.tasks'
   Sampler.GitHubTasks:
     - '*.ib.tasks'
+  DscResource.DocGenerator:
+    - 'Task.*'
 
 TaskHeader: |
   param($Path)

source/DSCResources/DSC_xArchive/DSC_xArchive.schema.mof

@@ -4,7 +4,7 @@ class DSC_xArchive : OMI_BaseResource
   [Key, Description("The path to the archive file that should be expanded to or removed from the specified destination.")] String Path;
   [Key, Description("The path where the specified archive file should be expanded to or removed from.")] String Destination;
   [Write, Description("Specifies whether or not the expanded content of the archive file at the specified path should exist at the specified destination. To update the specified destination to have the expanded content of the archive file at the specified path, specify this property as Present. To remove the expanded content of the archive file at the specified path from the specified destination, specify this property as Absent. The default value is Present."), ValueMap{"Present", "Absent"}, Values{"Present", "Absent"}] String Ensure;
-  [Write, Description("Specifies whether or not to validate that a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive by the specified checksum method. If the file does not match and Ensure is specified as Present and Force is not specified, the resource will throw an error that the file at the desintation cannot be overwritten. If the file does not match and Ensure is specified as Present and Force is specified, the file at the desintation will be overwritten. If the file does not match and Ensure is specified as Absent, the file at the desintation will not be removed. The default value is false.")] Boolean Validate;
+  [Write, Description("Specifies whether or not to validate that a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive by the specified checksum method. If the file does not match and Ensure is specified as Present and Force is not specified, the resource will throw an error that the file at the destination cannot be overwritten. If the file does not match and Ensure is specified as Present and Force is specified, the file at the destination will be overwritten. If the file does not match and Ensure is specified as Absent, the file at the destination will not be removed. The default value is false.")] Boolean Validate;
   [Write, Description("The Checksum method to use to validate whether or not a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive. An invalid argument exception will be thrown if Checksum is specified while Validate is specified as false. ModifiedDate will check that the LastWriteTime property of the file at the destination matches the LastWriteTime property of the file in the archive. CreatedDate will check that the CreationTime property of the file at the destination matches the CreationTime property of the file in the archive. SHA-1, SHA-256, and SHA-512 will check that the hash of the file at the destination by the specified SHA method matches the hash of the file in the archive by the specified SHA method. The default value is ModifiedDate.") ,ValueMap{"SHA-1", "SHA-256", "SHA-512", "CreatedDate", "ModifiedDate"}, Values{"SHA-1", "SHA-256", "SHA-512", "CreatedDate", "ModifiedDate"}] String Checksum;
   [Write, Description("The credential of a user account with permissions to access the specified archive path and destination if needed.") ,EmbeddedInstance("MSFT_Credential")] String Credential;
   [Write, Description("Specifies whether or not any existing files or directories at the destination with the same name as a file or directory in the archive should be overwritten to match the file or directory in the archive. When this property is false, an error will be thrown if an item at the destination needs to be overwritten. The default value is false.")] Boolean Force;

source/DSCResources/DSC_xArchive/README.md

@@ -0,0 +1,10 @@
+# Description
+
+Provides a mechanism to expand an archive (.zip) file to a specific path or
+remove an expanded archive (.zip) file from a specific path on a target node.
+
+## Requirements
+
+- The System.IO.Compression type assembly must be available on the machine.
+- The System.IO.Compression.FileSystem type assembly must be available on the
+  machine.

source/DSCResources/DSC_xArchive/en-US/DSC_xArchive.schema.mfl

@@ -4,7 +4,7 @@ class DSC_xArchive : OMI_BaseResource
   [Key,Description("The path to the archive file that should be expanded to or removed from the specified destination.") : Amended] String Path;
   [Key,Description("The path where the specified archive file should be expanded to or removed from.") : Amended] String Destination;
   [Description("Specifies whether or not the expanded content of the archive file at the specified path should exist at the specified destination. To update the specified destination to have the expanded content of the archive file at the specified path, specify this property as Present. To remove the expanded content of the archive file at the specified path from the specified destination, specify this property as Absent. The default value is Present.") : Amended] String Ensure;
-  [Description("Specifies whether or not to validate that a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive by the specified checksum method. If the file does not match and Ensure is specified as Present and Force is not specified, the resource will throw an error that the file at the desintation cannot be overwritten. If the file does not match and Ensure is specified as Present and Force is specified, the file at the desintation will be overwritten. If the file does not match and Ensure is specified as Absent, the file at the desintation will not be removed. The default value is false.") : Amended] Boolean Validate;
+  [Description("Specifies whether or not to validate that a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive by the specified checksum method. If the file does not match and Ensure is specified as Present and Force is not specified, the resource will throw an error that the file at the destination cannot be overwritten. If the file does not match and Ensure is specified as Present and Force is specified, the file at the destination will be overwritten. If the file does not match and Ensure is specified as Absent, the file at the destination will not be removed. The default value is false.") : Amended] Boolean Validate;
   [Description("The Checksum method to use to validate whether or not a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive. An invalid argument exception will be thrown if Checksum is specified while Validate is specified as false. ModifiedDate will check that the LastWriteTime property of the file at the destination matches the LastWriteTime property of the file in the archive. CreatedDate will check that the CreationTime property of the file at the destination matches the CreationTime property of the file in the archive. SHA-1, SHA-256, and SHA-512 will check that the hash of the file at the destination by the specified SHA method matches the hash of the file in the archive by the specified SHA method. The default value is ModifiedDate.") : Amended] String Checksum;
   [Description("The credential of a user account with permissions to access the specified archive path and destination if needed.") : Amended] String Credential;
   [Description("Specifies whether or not any existing files or directories at the destination with the same name as a file or directory in the archive should be overwritten to match the file or directory in the archive. When this property is false, an error will be thrown if an item at the destination needs to be overwritten. The default value is false.") : Amended] Boolean Force;

source/DSCResources/DSC_xArchive/en-US/DSC_xArchive.strings.psd1

@@ -49,7 +49,7 @@ ConvertFrom-StringData @'
     PathDoesNotContainValidPSDriveRoot = The path "{0}" cannot be accessed because it does not contain any directories to use as the root of a PSDrive.
     ErrorCreatingPSDrive = An error occurred while attempting to create a PSDrive to access the path "{0}" under the user "{1}".
     PathDoesNotExistAsLeaf = The path "{0}" does not exist or is not a path leaf.
-    DestinationExistsAsFile = A file exists at the desintation path "{0}".
+    DestinationExistsAsFile = A file exists at the destination path "{0}".
     ErrorOpeningArchive = An error occurred while attempting to open the archive at path "{0}".
     ErrorCopyingFromArchiveToDestination = An error occurred while attempting copy from the archive to the destination path "{0}".
     DirectoryIsNotEmpty = The directory at path "{0}" is not empty, so it will not be removed.

source/DSCResources/DSC_xDSCWebService/DSC_xDSCWebService.psm1

@@ -27,7 +27,7 @@ $script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'
         Prefix of the WCF SVC file.
 
     .PARAMETER ApplicationPoolName
-        The IIS ApplicationPool to use for the Pull Server. If not specified a
+        The IIS Application Pool to use for the Pull Server. If not specified a
         pool with name 'PSWS' will be created.
 
     .PARAMETER CertificateSubject
@@ -41,7 +41,7 @@ $script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'
         The thumbprint of the Certificate in CERT:\LocalMachine\MY\ for Pull Server.
 
     .PARAMETER ConfigureFirewall
-        Enable incomming firewall exceptions for the configured DSC Pull Server
+        Enable incoming firewall exceptions for the configured DSC Pull Server
         port. Defaults to true.
 
     .PARAMETER DisableSecurityBestPractices
@@ -259,7 +259,7 @@ function Get-TargetResource
         Specifies is self-signed certs will be accepted for client authentication.
 
     .PARAMETER ApplicationPoolName
-        The IIS ApplicationPool to use for the Pull Server. If not specified a
+        The IIS Application Pool to use for the Pull Server. If not specified a
         pool with name 'PSWS' will be created.
 
     .PARAMETER CertificateSubject
@@ -276,7 +276,7 @@ function Get-TargetResource
         The location on the disk where the Configuration is stored.
 
     .PARAMETER ConfigureFirewall
-        Enable incomming firewall exceptions for the configured DSC Pull Server
+        Enable incoming firewall exceptions for the configured DSC Pull Server
         port. Defaults to true.
 
     .PARAMETER DatabasePath
@@ -622,7 +622,7 @@ function Set-TargetResource
         Specifies is self-signed certs will be accepted for client authentication.
 
     .PARAMETER ApplicationPoolName
-        The IIS ApplicationPool to use for the Pull Server. If not specified a
+        The IIS Application Pool to use for the Pull Server. If not specified a
         pool with name 'PSWS' will be created.
 
     .PARAMETER CertificateSubject
@@ -639,7 +639,7 @@ function Set-TargetResource
         The location on the disk where the Configuration is stored.
 
     .PARAMETER ConfigureFirewall
-        Enable incomming firewall exceptions for the configured DSC Pull Server
+        Enable incoming firewall exceptions for the configured DSC Pull Server
         port. Defaults to true.
 
     .PARAMETER DatabasePath