Add docgenerator and hqrmtests (#21)

dsccommunity · Oct 8, 2024 · 890fa06 · 890fa06
1 parent 825cc8a
commit 890fa06
Show file tree

Hide file tree

Showing 12 changed files with 197 additions and 67 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,6 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `Test-StatementOpeningParenthsesOnSameLine` helper method.
   - Fixed type on `Test-StatementOpeningBrace*`.
   - `Measure-ParameterBlock*` format test data.
+- Enable generated docs with `DscResource.DocGenerator`
+- Add HQRM checks
 
 ### Fixed
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -70,12 +70,11 @@ prefixed with just 'Sql'
 Helper functions that are only used by one resource
 so preferably be put in the same script file as the resource.
 Helper function that can used by more than one resource can preferably
-be placed in the resource module file [DscResource.Common](/Modules/DscResource.Common/DscResource.Common.psm1).
+be placed in the resource module file [DscResource.Common](https://github.com/dsccommunity/DscResource.Common/).
 
 ### Localization
 
 Please see the localization section in the [style guideline](https://dsccommunity.org/styleguidelines/localization/).
-The helper functions is found in the module [DscResource.LocalizationHelper](/Modules/DscResource.LocalizationHelper/DscResource.LocalizationHelper.psm1).
 
 ### Unit tests
 
@@ -136,9 +135,6 @@ the automated test framework which is run in AppVeyor when commits are pushed
 to a Pull Request (PR).
 Please see the [Testing Guidelines](https://dsccommunity.org/guidelines/testing-guidelines/)
 for common DSC Resource Kit testing guidelines.
-There are also configurations made by existing integration tests that can be reused
-to write integration tests for other resources. This is documented in the
-[Integration tests README](/Tests/Integration/README.md).
 
 #### AppVeyor
 

diff --git a/README.md b/README.md
@@ -29,3 +29,8 @@ guidelines.
 ## Change log
 
 A full list of changes in each version can be found in the [change log](CHANGELOG.md).
+
+## Documentation
+
+The documentation can be found in the [DscResource.AnalyzerRules Wiki](https://github.com/dsccommunity/DscResource.AnalyzerRules/wiki).
+The documentation is automatically updated on each PR merge.
diff --git a/RequiredModules.psd1 b/RequiredModules.psd1
@@ -1,19 +1,25 @@
 @{
-    PSDependOptions       = @{
+    PSDependOptions            = @{
         AddToPath  = $true
         Target     = 'output\RequiredModules'
         Parameters = @{
             Repository = 'PSGallery'
         }
     }
 
-    InvokeBuild           = 'latest'
-    PSScriptAnalyzer      = 'latest'
-    Pester                = 'latest'
-    Plaster               = 'latest'
-    ModuleBuilder         = 'latest'
-    ChangelogManagement   = 'latest'
-    Sampler               = 'latest'
-    'Sampler.GitHubTasks' = 'latest'
-    'DscResource.Test'    = 'latest'
+    InvokeBuild                = 'latest'
+    PSScriptAnalyzer           = 'latest'
+    Pester                     = 'latest'
+    Plaster                    = 'latest'
+    ModuleBuilder              = 'latest'
+    ChangelogManagement        = 'latest'
+    Sampler                    = 'latest'
+    'Sampler.GitHubTasks'      = 'latest'
+    MarkdownLinkCheck          = 'latest'
+    'DscResource.Test'         = 'latest'
+    xDscResourceDesigner       = 'latest'
+
+    # Prerequisite modules for documentation.
+    'DscResource.DocGenerator' = 'latest'
+    PlatyPS                    = 'latest'
 }
diff --git a/Source/WikiSource/Home.md b/Source/WikiSource/Home.md
@@ -0,0 +1,17 @@
+# Welcome to the DscResource.AnalyzerRules wiki
+
+<sup>*DscResource.AnalyzerRules v#.#.#*</sup>
+
+For the task documentation please see the [README.md](https://github.com/dsccommunity/DscResource.AnalyzerRules/blob/main/README.md)
+
+Please leave comments, feature requests, and bug reports for this module in
+the [issues section](https://github.com/dsccommunity/DscResource.AnalyzerRules/issues)
+for this repository.
+
+## Prerequisites
+
+- [Sampler](https://github.com/gaelcolas/Sampler)
+
+## Change log
+
+A full list of changes in each version can be found in the [change log](https://github.com/dsccommunity/DscResource.AnalyzerRules/blob/main/CHANGELOG.md).
diff --git a/azure-pipelines.yml b/azure-pipelines.yml
@@ -54,6 +54,33 @@ stages:
   - stage: Test
     dependsOn: Build
     jobs:
+      - job: Test_HQRM
+        displayName: 'HQRM'
+        pool:
+          vmImage: 'windows-latest'
+        timeoutInMinutes: 0
+        steps:
+          - task: DownloadPipelineArtifact@2
+            displayName: 'Download Build Artifact'
+            inputs:
+              buildType: 'current'
+              artifactName: $(buildArtifactName)
+              targetPath: '$(Build.SourcesDirectory)/$(buildFolderName)'
+          - task: PowerShell@2
+            name: test
+            displayName: 'Run HQRM Test'
+            inputs:
+              filePath: './build.ps1'
+              arguments: '-Tasks hqrmtest'
+              pwsh: false
+          - task: PublishTestResults@2
+            displayName: 'Publish Test Results'
+            condition: succeededOrFailed()
+            inputs:
+              testResultsFormat: 'NUnit'
+              testResultsFiles: '$(buildFolderName)/$(testResultFolderName)/NUnit*.xml'
+              testRunTitle: 'HQRM'
+
       - job: test_linux
         displayName: 'Linux'
         timeoutInMinutes: 0

diff --git a/build.yaml b/build.yaml
@@ -10,11 +10,38 @@ Encoding: UTF8
 VersionedOutputDirectory: true
 BuiltModuleSubdirectory: builtModule
 
+####################################################
+#             HQRM Test Configuration              #
+####################################################
+DscTest:
+  Pester:
+    Configuration:
+      Filter:
+        Tag:
+        ExcludeTag:
+          - Common Tests - New Error-Level Script Analyzer Rules
+      Output:
+        Verbosity: Detailed
+        CIFormat: Auto
+      TestResult:
+        Enabled: true
+        OutputFormat: NUnitXML
+        OutputEncoding: ascii
+        OutputPath: ./output/testResults/NUnitXml_HQRM_Tests.xml
+  Script:
+    ExcludeSourceFile:
+      - output
+      - DscResource.AnalyzerRules
+    ExcludeModuleFile:
+    MainGitBranch: main
+
 ModuleBuildTasks:
   Sampler:
     - '*.build.Sampler.ib.tasks'
   Sampler.GitHubTasks:
     - '*.ib.tasks'
+  DscResource.DocGenerator:
+    - 'Task.*'
   DscResource.Test:
     - 'Task.*'
 
@@ -43,10 +70,23 @@ BuildWorkflow:
     - Build_NestedModules_ModuleBuilder
     - Create_changelog_release_output
 
+  docs:
+    - Generate_Wiki_Content
+    - Generate_Conceptual_Help
+    - Generate_Markdown_For_Public_Commands
+    - Generate_External_Help_File_For_Public_Commands
+    - Clean_Markdown_Of_Public_Commands
+    - Generate_Wiki_Sidebar
+    - Clean_Markdown_Metadata
+
   pack:
     - build
+    - docs
     - package_module_nupkg
 
+  hqrmtest:
+    - Invoke_HQRM_Tests_Stop_On_Fail
+
   test:
     - Pester_Tests_Stop_On_Fail
     - Convert_Pester_Coverage
@@ -58,6 +98,7 @@ BuildWorkflow:
   publish:
     - Publish_Release_To_GitHub
     - Publish_Module_To_gallery
+    - Publish_GitHub_Wiki_Content
 
 ####################################################
 #          Pester Configuration (Sampler)          #
@@ -106,3 +147,31 @@ GitHubConfig:
   GitHubConfigUserName: dscbot # cSpell: disable-line
   GitHubConfigUserEmail: [email protected]
   UpdateChangelogOnPrerelease: false
+
+####################################################
+#      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)
+  Publish_GitHub_Wiki_Content:
+    Debug: true
+  Generate_Wiki_Content:
+    MofResourceMetadata:
+      Type: MofResource
+      Category: Resources
+    ClassResourceMetadata:
+      Type: ClassResource
+      Category: Resources
+    CompositeResourceMetadata:
+      Type: CompositeResource
+      Category: Resources
+  Generate_Wiki_Sidebar:
+    Debug: false
+    AlwaysOverwrite: true
diff --git a/source/Private/Get-LocalizedData.ps1 b/source/Private/Get-LocalizedData.ps1
@@ -133,7 +133,8 @@
 function Get-LocalizedData
 {
     [CmdletBinding()]
-    param (
+    param
+    (
         [Parameter(Position = 0)]
         [Alias('Variable')]
         [ValidateNotNullOrEmpty()]

diff --git a/source/Private/New-SuggestedCorrection.ps1 b/source/Private/New-SuggestedCorrection.ps1
@@ -14,7 +14,8 @@ function New-SuggestedCorrection
 {
     [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'None')]
     [OutputType([Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.CorrectionExtent])]
-    param (
+    param
+    (
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.Language.IScriptExtent]
         $Extent,

diff --git a/source/Private/Test-StatementOpeningParenthsesOnSameLine.ps1 b/source/Private/Test-StatementOpeningParenthsesOnSameLine.ps1
@@ -32,7 +32,6 @@ function Test-StatementOpeningParenthsesOnSameLine
     [System.String[]] $statementBlockRows = Get-StatementBlockAsRow -StatementBlock $StatementBlock
     if ($statementBlockRows.Count)
     {
-
         # Check so that an opening brace does not exist on the same line as the statement.
         if ($statementBlockRows[0] -match '\(')
         {

diff --git a/source/Public/Measure-Hashtable.ps1 b/source/Public/Measure-Hashtable.ps1
@@ -21,7 +21,8 @@ function Measure-Hashtable
 {
     [CmdletBinding()]
     [OutputType([Microsoft.Windows.Powershell.ScriptAnalyzer.Generic.DiagnosticRecord[]])]
-    param (
+    param
+    (
         [Parameter(Mandatory = $true)]
         [ValidateNotNullOrEmpty()]
         [System.Management.Automation.Language.HashtableAst[]]