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

Author: PlagueHO

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

README.md

@@ -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'

RequiredModules.psd1

@@ -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'

azure-pipelines.yml

@@ -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