Add Autodocumentation Generation - Fixes #110 (#111)

* Add Autodocumentation Generation - Issue #110 * Fix issue with MOF
dsccommunity · Mar 25, 2020 · 2cd76ce · 2cd76ce
1 parent 663a3ad
commit 2cd76ce
Show file tree

Hide file tree

Showing 11 changed files with 230 additions and 27 deletions.
diff --git a/.gitattributes b/.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
diff --git a/.gitignore b/.gitignore
@@ -2,6 +2,7 @@
 *.user
 *.coverage
 .vs
+.vscode
 .psproj
 .sln
 markdownissues.txt

diff --git a/.vscode/analyzersettings.psd1 b/.vscode/analyzersettings.psd1
@@ -1,11 +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.
         'PSAvoidDefaultValueForMandatoryParameter',
@@ -43,11 +38,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-*'
     )
 }
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -1,7 +1,6 @@
-// Place your settings in this file to overwrite default and user settings.
 {
     "powershell.codeFormatting.openBraceOnSameLine": false,
-    "powershell.codeFormatting.newLineAfterOpenBrace": false,
+    "powershell.codeFormatting.newLineAfterOpenBrace": true,
     "powershell.codeFormatting.newLineAfterCloseBrace": true,
     "powershell.codeFormatting.whitespaceBeforeOpenBrace": true,
     "powershell.codeFormatting.whitespaceBeforeOpenParen": true,
@@ -10,7 +9,30 @@
     "powershell.codeFormatting.ignoreOneLineBlock": false,
     "powershell.codeFormatting.pipelineIndentationStyle": "IncreaseIndentationAfterEveryPipeline",
     "powershell.codeFormatting.preset": "Custom",
+    "powershell.codeFormatting.alignPropertyValuePairs": true,
     "files.trimTrailingWhitespace": true,
     "files.insertFinalNewline": true,
-    "powershell.scriptAnalysis.settingsPath": ".vscode\\analyzersettings.psd1"
+    "powershell.scriptAnalysis.settingsPath": ".vscode\\analyzersettings.psd1",
+    "powershell.scriptAnalysis.enable": true,
+    "files.associations": {
+        "*.ps1xml": "xml"
+    },
+    "cSpell.words": [
+        "COMPANYNAME",
+        "ICONURI",
+        "LICENSEURI",
+        "PROJECTURI",
+        "RELEASENOTES",
+        "buildhelpers",
+        "endregion",
+        "gitversion",
+        "icontains",
+        "keepachangelog",
+        "notin",
+        "pscmdlet",
+        "steppable"
+    ],
+    "[markdown]": {
+        "files.encoding": "utf8"
+    }
 }
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -0,0 +1,125 @@
+{
+    "version": "2.0.0",
+    "_runner": "terminal",
+    "windows": {
+        "options": {
+            "shell": {
+                "executable": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
+                "args": [
+                    "-NoProfile",
+                    "-ExecutionPolicy",
+                    "Bypass",
+                    "-Command"
+                ]
+            }
+        }
+    },
+    "linux": {
+        "options": {
+            "shell": {
+                "executable": "/usr/bin/pwsh",
+                "args": [
+                    "-NoProfile",
+                    "-Command"
+                ]
+            }
+        }
+    },
+    "osx": {
+        "options": {
+            "shell": {
+                "executable": "/usr/local/bin/pwsh",
+                "args": [
+                    "-NoProfile",
+                    "-Command"
+                ]
+            }
+        }
+    },
+    "tasks": [
+        {
+            "label": "build",
+            "type": "shell",
+            "command": "&${cwd}/build.ps1",
+            "args": ["-AutoRestore"],
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": true,
+                "panel": "new",
+                "clear": false
+            },
+            "runOptions": {
+                "runOn": "default"
+            },
+            "problemMatcher": [
+                {
+                    "owner": "powershell",
+                    "fileLocation": [
+                        "absolute"
+                    ],
+                    "severity": "error",
+                    "pattern": [
+                        {
+                            "regexp": "^\\s*(\\[-\\]\\s*.*?)(\\d+)ms\\s*$",
+                            "message": 1
+                        },
+                        {
+                            "regexp": "(.*)",
+                            "code": 1
+                        },
+                        {
+                            "regexp": ""
+                        },
+                        {
+                            "regexp": "^.*,\\s*(.*):\\s*line\\s*(\\d+).*",
+                            "file": 1,
+                            "line": 2
+                        }
+                    ]
+                }
+            ]
+        },
+        {
+            "label": "test",
+            "type": "shell",
+            "command": "&${cwd}/build.ps1",
+            "args": ["-AutoRestore","-Tasks","test"],
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": true,
+                "panel": "dedicated",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": [
+                {
+                    "owner": "powershell",
+                    "fileLocation": [
+                        "absolute"
+                    ],
+                    "severity": "error",
+                    "pattern": [
+                        {
+                            "regexp": "^\\s*(\\[-\\]\\s*.*?)(\\d+)ms\\s*$",
+                            "message": 1
+                        },
+                        {
+                            "regexp": "(.*)",
+                            "code": 1
+                        },
+                        {
+                            "regexp": ""
+                        },
+                        {
+                            "regexp": "^.*,\\s*(.*):\\s*line\\s*(\\d+).*",
+                            "file": 1,
+                            "line": 2
+                        }
+                    ]
+                }
+            ]
+        }
+    ]
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,3 +21,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated to use continuous delivery pattern using Azure DevOps - Fixes
   [Issue #105](https://github.com/dsccommunity/ActiveDirectoryCSDsc/issues/105).
 - Fixed build badge IDs - Fixes [Issue #108](https://github.com/dsccommunity/ActiveDirectoryCSDsc/issues/108).
+- Corrected MOF formatting of `DSC_AdcsAuthorityInformationAccess.schema.mof`
+  to fix issue with auto documentation generation.
+
+### Added
+
+- Added build task `Generate_Conceptual_Help` to generate conceptual help
+  for the DSC resource.
+- Added build task `Generate_Wiki_Content` to generate the wiki content
+  that can be used to update the GitHub Wiki.
+
+### Changed
+
+- Updated CI pipeline files.
+- No longer run integration tests when running the build task `test`, e.g.
+  `.\build.ps1 -Task test`. To manually run integration tests, run the
+  following:
+  ```powershell
+  .\build.ps1 -Tasks test -PesterScript 'tests/Integration' -CodeCoverageThreshold 0
+  ```
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,7 @@
+# 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)
diff --git a/RequiredModules.psd1 b/RequiredModules.psd1
@@ -1,20 +1,22 @@
 @{
-    # Set up a mini virtual environment...
     PSDependOptions      = @{
         AddToPath  = $true
         Target     = 'output\RequiredModules'
         Parameters = @{
+            Repository = ''
         }
     }
 
-    invokeBuild                 = 'latest'
+    InvokeBuild                 = 'latest'
     PSScriptAnalyzer            = 'latest'
-    pester                      = 'latest'
+    Pester                      = 'latest'
     Plaster                     = 'latest'
     ModuleBuilder               = '1.0.0'
     ChangelogManagement         = 'latest'
     Sampler                     = 'latest'
+    MarkdownLinkCheck           = 'latest'
     'DscResource.Test'          = 'latest'
     'DscResource.AnalyzerRules' = 'latest'
+    'DscResource.DocGenerator'  = 'latest'
     xDscResourceDesigner        = 'latest'
 }
diff --git a/build.ps1 b/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,26 +35,37 @@ 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,
+    [switch]$ResolveDependency,
 
     [Parameter(DontShow)]
     [AllowNull()]
@@ -211,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')
@@ -309,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

diff --git a/build.yaml b/build.yaml
@@ -22,6 +22,8 @@ BuildWorkflow:
     - Build_Module_ModuleBuilder
     - Build_NestedModules_ModuleBuilder
     - Create_changelog_release_output
+    - Generate_Conceptual_Help
+    - Generate_Wiki_Content
 
   pack:
     - build
@@ -68,6 +70,8 @@ Resolve-Dependency:
 ModuleBuildTasks:
   Sampler:
     - '*.build.Sampler.ib.tasks'
+  DscResource.DocGenerator:
+    - 'Task.*'
 
 TaskHeader: |
   param($Path)

diff --git a/...esources/DSC_AdcsAuthorityInformationAccess/DSC_AdcsAuthorityInformationAccess.schema.mof b/...esources/DSC_AdcsAuthorityInformationAccess/DSC_AdcsAuthorityInformationAccess.schema.mof
@@ -1,5 +1,5 @@
 [ClassVersion("1.0.0.0"), FriendlyName("AdcsAuthorityInformationAccess")]
-class DSC_AdcsAuthorityInformationAccess: OMI_BaseResource
+class DSC_AdcsAuthorityInformationAccess : OMI_BaseResource
 {
     [Key, Description("Specifies the resource is a single instance, the value must be 'Yes'."), ValueMap{"Yes"}, Values{"Yes"}] String IsSingleInstance;
     [Write, Description("Specifies the list of URIs that should be included in the AIA extension of the issued certificate.")] String AiaUri[];
-Original file line number
+Diff line change
@@ Expand Up / @@ -2,6 +2,7 @@ @@
     *.user
     *.coverage
     .vs
+    .vscode
     .psproj
     .sln
     markdownissues.txt
@@ Expand Down @@