en-US/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 resources. Documentation is composed of
    markdown files that can be optionally shipped with a module.
    When markdown documentation is defined, this content will be used instead of
    inline synopsis comments. Markdown documentation is supported for rules and
    suppression groups.
 
    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 FOR RULES
    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
    }
 
    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`.
     
    ### Creating documentation for suppression groups
     
    Suppression groups support documentation similar to rules that allows a synopsis to be defined.
    Other sections can be added to the markdown content, but are ignored.
    Set the synopsis in markdown to allow a culture specific message to be displayed.
     
    The markdown of each file uses following structure.
 
text
{{ Annotations }}
{{ NAME OF SUPPRESSION GROUP }}
SYNOPSIS
    {{ A brief summary of the suppression group }}
```
 
    STORING MARKDOWN FILES
    The location PSRule uses to find markdown documentation depends on how the
    rules/ resources are packaged. In each case, documentation will be in a
    culture `/<culture>/`specific subdirectory. Resources can be either shipped
    as part of a module, or standalone.
    - When resources are standalone, the culture subdirectory is relative to the
    `
    .Rule.
    ` file. - When packaged in a module, the culture subdirectory is relative to
    the module manifest `.psd1` file.
    The `<culture>` subdirectory will be the current culture that PowerShell is
    executed under. To determine the current culture use `(Get-Culture).Name`.
    Alternatively, the culture can set by using the `-Culture` parameter of
    PSRule cmdlets.
 
NOTE
    An online version of this document is available at
    https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Docs/.
 
SEE ALSO
    -
    Get-PSRuleHelp
 
KEYWORDS
    - Help
- Rule