en-GB/about_PSRule_Docs.help.txt

TOPIC
    about_psrule_docs
 
SHORT DESCRIPTION
    Describes usage of documentation within PSRule.
 
LONG DESCRIPTION
    PSRule includes a built-in documentation system that provide culture
    specific help and metadata for rules. Rule documentation is composed of
    markdown files that can be optionally shipped with a module.
 
    GETTING DOCUMENTATION
    To get documentation for a rule use the `Get-PSRuleHelp` cmdlet.
    For example:
 
    Get-PSRuleHelp <rule-name>
 
    Each rule can include the following documentation:
    - Annotations - Additional metadata included in results.
    - Synopsis - A brief description on the intended purpose of the rule.
    - Description - A detailed description on the intended purpose of the rule.
    - Recommendation - A detailed explanation of the requirements to pass the rule.
    - Notes - Any additional information or configuration options.
    - Links - Any links to external references.
    See cmdlet help for detailed information on the `Get-PSRuleHelp` cmdlet.
 
    ONLINE HELP
    Rule documentation may optionally include a link to an online version. When
    included, the `-Online` parameter can be used to open the online version in
    the default web browser.
    For example:
 
    Get-PSRuleHelp <rule-name> -Online
 
    CREATING DOCUMENTATION
    Rule documentation is composed of markdown files, one per rule. When
    creating rules for more then one culture, a separate markdown file is
    created per rule per culture.
    The markdown files for each rule is automatically discovered based on naming convention.
    Markdown is saved in a file with the same filename as the rule name with the
    `.md` extension. The file name should match the same case exactly, with a
    lower case extension.
    As an example, the `storageAccounts.UseHttps.md` markdown file would be
    created.
 
    # Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB
    Rule 'storageAccounts.UseHttps' -If { ResourceType 'Microsoft.Storage/storageAccounts' } {
        Recommend 'Storage accounts should only allow secure traffic'
     
        $TargetObject.Properties.supportsHttpsTrafficOnly
    }
 
    This directory PSRule will look for these markdown files depends on how the
    rules are packaged:
    - If the rules are loose (not part of a module), PSRule will search for
    documentation in the `.<culture>` subdirectory relative to where the rule
    script
    .ps1
    file is located. - When the rules are shipped as part of a module, PSRule
    will search for documentation in the `.<culture>` subdirectory relative to
    where the module manifest
    .psd1
    file is located.
    The `<culture>` subdirectory will be the current culture that PowerShell is
    executed under (the same as `(Get-Culture).Name`). Alternatively, the
    culture can set by using the `-Culture` parameter of PSRule cmdlets.
    The markdown of each file uses following structure.
 
```text
{{ Annotations }}
{{ NAME OF RULE }}
SYNOPSIS
    {{ A brief summary of the rule }}
 
DESCRIPTION
    {{ A detailed description of the rule }}
 
RECOMMENDATION
    {{ A detailed explanation of the steps required to pass the rule }}
 
NOTES
    {{ Additional information or configuration options }}
 
LINKS
    {{ Links to external references }}
    ```
    Optionally, one or more annotations formatted as YAML key value pairs can be
    included. i.e. `severity: Critical`
    Additional sections such as `EXAMPLES` can be included although are not
    exposed with `Get-PSRuleHelp`.
 
NOTE
    An online version of this document is available at
    https://github.com/Microsoft/PSRule/blob/main/docs/concepts/PSRule/en-US/about_PSRule_Docs.md.
 
SEE ALSO
    -
    Get-PSRuleHelp
 
KEYWORDS
    - Help
- Rule