Add markdown help #157 #18 #148 #147 (#159)

- Added rule documentation, which allows additional rule information to be stored in markdown files. #157 - Rule documentation also adds culture support. #18 - Added annotations, which are non-indexed metadata stored in rule documentation. #148 - Annotations can contain a link to online version of the documentation. #147
microsoft · Jun 2, 2019 · 6844497 · 6844497
1 parent dd34fdd
commit 6844497
Show file tree

Hide file tree

Showing 54 changed files with 3,762 additions and 112 deletions.
diff --git a/azure-pipelines.yml → .azure-pipelines/azure-pipelines.yaml b/azure-pipelines.yml → .azure-pipelines/azure-pipelines.yaml
@@ -29,11 +29,11 @@ pool:
 steps:
 
 # Install pipeline dependencies and build module
-- powershell: ./scripts/pipeline-build.ps1 -File ./PSRule.build.ps1 -Configuration $(buildConfiguration) -ModuleVersion $(Build.BuildNumber) -ReleaseVersion "$(Release.Version)"
+- powershell: ./.azure-pipelines/pipeline-build.ps1 -File ./pipeline.build.ps1 -Configuration $(buildConfiguration) -ModuleVersion $(Build.BuildNumber) -ReleaseVersion "$(Release.Version)"
   displayName: 'Build module'
 
 # Run module benchmark
-- powershell: ./scripts/pipeline-build.ps1 -Task Benchmark -File ./PSRule.build.ps1 -Configuration $(buildConfiguration) -ModuleVersion $(Build.BuildNumber) -ReleaseVersion "$(Release.Version)"
+- powershell: ./.azure-pipelines/pipeline-build.ps1 -Task Benchmark -File ./pipeline.build.ps1 -Configuration $(buildConfiguration) -ModuleVersion $(Build.BuildNumber) -ReleaseVersion "$(Release.Version)"
   displayName: 'Benchmark'
   condition: eq(variables['benchmark'], 'true')
 

diff --git a/scripts/pipeline-build.ps1 → .azure-pipelines/pipeline-build.ps1 b/scripts/pipeline-build.ps1 → .azure-pipelines/pipeline-build.ps1
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,12 @@
 
 ## Unreleased
 
+- Added rule documentation, which allows additional rule information to be stored in markdown files. [#157](https://github.com/BernieWhite/PSRule/issues/157)
+  - Rule documentation also adds culture support. [#18](https://github.com/BernieWhite/PSRule/issues/18)
+  - Rule documentation can be access like help with the `Get-PSRuleHelp` cmdlet.
+- Added annotations, which are non-indexed metadata stored in rule documentation. [#148](https://github.com/BernieWhite/PSRule/issues/148)
+  - Annotations can contain a link to online version of the documentation. [#147](https://github.com/BernieWhite/PSRule/issues/147)
+
 ## v0.6.0-B190514 (pre-release)
 
 - Fix operation is not supported on this platform failure. [#152](https://github.com/BernieWhite/PSRule/issues/152)

diff --git a/README.md b/README.md
@@ -153,6 +153,7 @@ The following language keywords are used by the `PSRule` module:
 The following commands exist in the `PSRule` module:
 
 - [Get-PSRule](docs/commands/PSRule/en-US/Get-PSRule.md) - Get a list of rule definitions.
+- [Get-PSRuleHelp](docs/commands/PSRule/en-US/Get-PSRuleHelp.md) - Get documentation for a rule.
 - [Invoke-PSRule](docs/commands/PSRule/en-US/Invoke-PSRule.md) - Evaluate objects against matching rules.
 - [New-PSRuleOption](docs/commands/PSRule/en-US/New-PSRuleOption.md) - Create options to configure PSRule execution.
 - [Set-PSRuleOption](docs/commands/PSRule/en-US/Set-PSRuleOption.md) - Sets options that configure PSRule execution.

diff --git a/docs/commands/PSRule/en-US/Get-PSRule.md b/docs/commands/PSRule/en-US/Get-PSRule.md
@@ -15,7 +15,7 @@ Get a list of rule definitions.
 
 ```text
 Get-PSRule [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>]
- [-Module <String[]>] [-ListAvailable] [<CommonParameters>]
+ [-Module <String[]>] [-ListAvailable] [-Culture <String>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -148,6 +148,26 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Culture
+
+Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
+
+This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
+
+The PowerShell cmdlet `Get-Culture` shows the current culture of PowerShell.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

diff --git a/docs/commands/PSRule/en-US/Get-PSRuleHelp.md b/docs/commands/PSRule/en-US/Get-PSRuleHelp.md
@@ -0,0 +1,139 @@
+---
+external help file: PSRule-help.xml
+Module Name: PSRule
+online version: https://berniewhite.github.io/PSRule/commands/PSRule/en-US/Get-PSRuleHelp.html
+schema: 2.0.0
+---
+
+# Get-PSRuleHelp
+
+## SYNOPSIS
+
+Get documentation for a rule.
+
+## SYNTAX
+
+```text
+Get-PSRuleHelp [-Name] <String> [-Path <String>] [-Module <String>] [-Culture <String>] [-Online]
+ [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+Get documentation for a rule.
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+Get-PSRuleHelp Azure.ACR.AdminUser;
+```
+
+Get rule documentation for the rule `Azure.ACR.AdminUser`.
+
+### Example 2
+
+```powershell
+Get-PSRuleHelp Azure.ACR.AdminUser -Online;
+```
+
+Browse to the online version of documentation for `Azure.ACR.AdminUser` using the default web browser.
+
+## PARAMETERS
+
+### -Name
+
+The name of the rule to get documentation for.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases: n
+
+Required: True
+Position: 1
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: True
+```
+
+### -Path
+
+A path to check documentation for. If this is not specified, documentation is sourced for imported modules.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases: p
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Module
+
+Limit returned information to rules in the specified module.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Culture
+
+Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
+
+This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
+
+The PowerShell cmdlet `Get-Culture` shows the current culture of PowerShell.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Online
+
+Instead of displaying documentation within PowerShell, browse to the online version using the default web browser.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## OUTPUTS
+
+### PSRule.Rules.RuleHelpInfo
+
+## NOTES
+
+## RELATED LINKS
diff --git a/docs/commands/PSRule/en-US/Invoke-PSRule.md b/docs/commands/PSRule/en-US/Invoke-PSRule.md
@@ -18,15 +18,17 @@ Evaluate objects against matching rules.
 ```text
 Invoke-PSRule [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] -InputObject <PSObject>
  [-Outcome <RuleOutcome>] [-Option <PSRuleOption>] [-As <ResultFormat>] [-Format <InputFormat>]
- [-ObjectPath <String>] [-Module <String[]>] [-OutputFormat <OutputFormat>] [<CommonParameters>]
+ [-ObjectPath <String>] [-Module <String[]>] [-OutputFormat <OutputFormat>] [-Culture <String>]
+ [<CommonParameters>]
 ```
 
 ### InputPath
 
 ```text
 Invoke-PSRule [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Outcome <RuleOutcome>]
  [-Option <PSRuleOption>] [-As <ResultFormat>] [-Format <InputFormat>] [-ObjectPath <String>]
- [-Module <String[]>] [-OutputFormat <OutputFormat>] -InputPath <String[]> [<CommonParameters>]
+ [-Module <String[]>] [-OutputFormat <OutputFormat>] -InputPath <String[]> [-Culture <String>]
+ [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -330,6 +332,26 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Culture
+
+Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
+
+This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
+
+The PowerShell cmdlet `Get-Culture` shows the current culture of PowerShell.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

diff --git a/docs/commands/PSRule/en-US/PSRule.md b/docs/commands/PSRule/en-US/PSRule.md
@@ -18,6 +18,10 @@ A PowerShell rules engine.
 
 Get a list of matching rule definitions within the search path.
 
+### [Get-PSRule](Get-PSRuleHelp.md)
+
+Get documentation for a rule.
+
 ### [Invoke-PSRule](Invoke-PSRule.md)
 
 Evaluate pipeline objects against matching rules.

diff --git a/docs/commands/PSRule/en-US/Test-PSRuleTarget.md b/docs/commands/PSRule/en-US/Test-PSRuleTarget.md
@@ -18,14 +18,15 @@ Pass or fail objects against matching rules.
 ```text
 Test-PSRuleTarget [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] -InputObject <PSObject>
  [-Option <PSRuleOption>] [-Format <InputFormat>] [-ObjectPath <String>] [-Module <String[]>]
- [<CommonParameters>]
+ [-Culture <String>] [<CommonParameters>]
 ```
 
 ### InputPath
 
 ```text
 Test-PSRuleTarget [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>]
- [-Format <InputFormat>] [-ObjectPath <String>] [-Module <String[]>] -InputPath <String[]> [<CommonParameters>]
+ [-Format <InputFormat>] [-ObjectPath <String>] [-Module <String[]>] -InputPath <String[]> [-Culture <String>]
+ [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -211,6 +212,26 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Culture
+
+Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
+
+This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
+
+The PowerShell cmdlet `Get-Culture` shows the current culture of PowerShell.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

diff --git a/docs/commands/PSRule/en-US/toc.yml b/docs/commands/PSRule/en-US/toc.yml
@@ -6,6 +6,9 @@
     - name: Get-PSRule
       href: Get-PSRule.md
       topicHref: Get-PSRule.md
+    - name: Get-PSRuleHelp
+      href: Get-PSRuleHelp.md
+      topicHref: Get-PSRuleHelp.md
     - name: Invoke-PSRule
       href: Invoke-PSRule.md
       topicHref: Invoke-PSRule.md

diff --git a/PSRule.build.ps1 → pipeline.build.ps1 b/PSRule.build.ps1 → pipeline.build.ps1
@@ -1,7 +1,7 @@
-
+[CmdletBinding()]
 param (
     [Parameter(Mandatory = $False)]
-    [String]$ModuleVersion,
+    [String]$ModuleVersion = '0.0.1',
 
     [Parameter(Mandatory = $False)]
     [AllowNull()]
@@ -23,10 +23,26 @@ param (
     [String]$ArtifactPath = (Join-Path -Path $PWD -ChildPath out/modules)
 )
 
-if ($Env:COVERAGE -eq 'true') {
+Write-Host -Object "[Pipeline] -- PWD: $PWD" -ForegroundColor Green;
+Write-Host -Object "[Pipeline] -- ArtifactPath: $ArtifactPath" -ForegroundColor Green;
+Write-Host -Object "[Pipeline] -- BuildNumber: $($Env:BUILD_BUILDNUMBER)" -ForegroundColor Green;
+Write-Host -Object "[Pipeline] -- SourceBranch: $($Env:BUILD_SOURCEBRANCH)" -ForegroundColor Green;
+Write-Host -Object "[Pipeline] -- SourceBranchName: $($Env:BUILD_SOURCEBRANCHNAME)" -ForegroundColor Green;
+
+if ($Env:SYSTEM_DEBUG -eq 'true') {
+    $VerbosePreference = 'Continue';
+}
+
+if ($Env:coverage -eq 'true') {
     $CodeCoverage = $True;
 }
 
+if ($Env:BUILD_SOURCEBRANCH -contains '/tags/' -and $Env:BUILD_SOURCEBRANCHNAME -like "v0.") {
+    $ModuleVersion = $Env:BUILD_SOURCEBRANCHNAME.Substring(1);
+}
+
+Write-Host -Object "[Pipeline] -- ModuleVersion: $ModuleVersion" -ForegroundColor Green;
+
 # Copy the PowerShell modules files to the destination path
 function CopyModuleFiles {
 
@@ -60,7 +76,8 @@ function CopyModuleFiles {
 task BuildDotNet {
     exec {
         # Build library
-        dotnet publish src/PSRule -c $Configuration -f netstandard2.0 -o $(Join-Path -Path $PWD -ChildPath out/modules/PSRule/core)
+        # Add build version -p:versionPrefix=$ModuleVersion
+        dotnet publish src/PSRule -c $Configuration -f netstandard2.0 -o $(Join-Path -Path $PWD -ChildPath out/modules/PSRule)
     }
 }
 
@@ -106,7 +123,6 @@ task Clean {
 }
 
 task VersionModule {
-
     if (![String]::IsNullOrEmpty($ReleaseVersion)) {
         Write-Verbose -Message "[VersionModule] -- ReleaseVersion: $ReleaseVersion";
         $ModuleVersion = $ReleaseVersion;

diff --git a/src/PSRule/Annotations/BlockMetadata.cs b/src/PSRule/Annotations/BlockMetadata.cs
@@ -3,7 +3,7 @@
     /// <summary>
     /// Metadata properties that can be exposed by comment help.
     /// </summary>
-    public sealed class BlockMetadata
+    internal sealed class BlockMetadata
     {
         public string Description;
     }