Publish v2 docs #68 (microsoft#894)

* Publish v2 docs #68

Improve documentation on features and how to use them.

* Fix file headers

* Update docs path

.github/workflows/docs.yaml

@@ -42,4 +42,4 @@ jobs:
           python3 -m pip install -r requirements-docs.txt
 
       - name: Deploy site
-        run: mike deploy --push --update-aliases v1 stable
+        run: mike deploy --push --update-aliases v2 latest --title 'v2 (preview)'

README.md

@@ -68,7 +68,7 @@ Visual Studio Code | Visual Studio Code extension for PSRule. | [latest][extensi
 The following example shows basic PSRule usage for validating PowerShell objects.
 For specific use cases see [scenarios](#scenarios).
 
-For frequently asked questions, see the [FAQ](docs/features.md#frequently-asked-questions-faq).
+For frequently asked questions, see the [FAQ](https://microsoft.github.io/PSRule/faq/).
 
 ### Define a rule
 
@@ -218,9 +218,9 @@ For walk through examples of PSRule usage see:
 - [Validate Azure resource configuration](docs/scenarios/azure-resources/azure-resources.md)
 - [Validate Azure resources tags](docs/scenarios/azure-tags/azure-tags.md)
 - [Validate Kubernetes resources](docs/scenarios/kubernetes-resources/kubernetes-resources.md)
-- [Using within continuous integration](docs/scenarios/validation-pipeline/validation-pipeline.md)
+- [Using within continuous integration](https://microsoft.github.io/PSRule/scenarios/validation-pipeline/validation-pipeline/)
 - [Packaging rules in a module](docs/scenarios/rule-module/rule-module.md)
-- [Writing rule help](docs/scenarios/rule-docs/rule-docs.md)
+- [Writing rule help](https://microsoft.github.io/PSRule/authoring/writing-rule-help/)
 
 ## Language reference
 

docs/CHANGELOG-v0.md

@@ -642,7 +642,7 @@ What's changed since v0.8.0:
     - Baselines can be packaged within module.
     - Modules can specify a default baseline in module manifest.
     - Target binding options (`Binding`) are now part of baselines.
-    - See [about_PSRule_Baseline](concepts/PSRule/en-US/about_PSRule_Baseline.md) for more information.
+    - See [about_PSRule_Baseline] for more information.
 - Bug fixes:
   - Fix can not serialize nested System.IO.DirectoryInfo property. [#281](https://github.com/Microsoft/PSRule/issues/281)
   - Fix ModuleName not displayed in Get-PSRuleHelp list. [#275](https://github.com/Microsoft/PSRule/issues/275)
@@ -670,7 +670,7 @@ What's changed since pre-release v0.9.0-B190905:
     - Target binding options (`Binding`) are now part of baselines.
   - The previous `baseline` options property has been renamed to `rule`.
   - The previous `configuration` property is now a top level option.
-  - See [about_PSRule_Baseline](concepts/PSRule/en-US/about_PSRule_Baseline.md) for more information.
+  - See [about_PSRule_Baseline] for more information.
 
 ## v0.9.0-B190819 (pre-release)
 
@@ -1077,3 +1077,5 @@ What's changed since pre-release v0.1.0-B181235:
 ## v0.1.0-B181212 (pre-release)
 
 - Initial pre-release.
+
+[about_PSRule_Baseline]: concepts/PSRule/en-US/about_PSRule_Baseline.md

docs/about.md

@@ -0,0 +1,21 @@
+---
+author: BernieWhite
+---
+
+# What is PSRule?
+
+PSRule is a rules engine geared towards testing Infrastructure as Code (IaC).
+Rules you write or import perform static analysis on IaC artifacts such as:
+templates, manifests, pipelines, and workflows.
+
+## Why use PSRule?
+
+PSRule aims to provide a rich experience for building and running static analysis tests on IaC.
+While this has some similarities to traditional testing frameworks it extends on the following:
+
+- **Reuse and share** — existing pre-built rules, configure, or write your own.
+- **Incremental adoption** — with baselines allows you to keep moving forward.
+- **Handle exceptions** — and keep exceptions auditable in git history.
+- **Documentation** — provides recommendations and examples instead of just pass or fail.
+
+*[IaC]: Infrastructure as Code

docs/addon-modules.md

@@ -0,0 +1,34 @@
+# Additional modules
+
+## Pre-built rules
+
+The following modules contain pre-built rules that can be plugged into your pipeline.
+
+Module                    | Description | Version / downloads
+------                    | ----------- | -------------------
+[PSRule.Rules.Azure]      | A suite of rules to validate Azure resources and infrastructure as code (IaC) using PSRule. | [![rules-azure-version-badge]][rules-azure-version-module] [![rules-azure-downloads-badge]][rules-azure-version-module]
+[PSRule.Rules.Kubernetes] | A suite of rules to validate Kubernetes resources using PSRule. | [![rules-kubernetes-version-badge]][rules-kubernetes-version-module] [![rules-kubernetes-downloads-badge]][rules-kubernetes-version-module]
+[PSRule.Rules.CAF]        | A suite of rules to validate Azure resources against the Cloud Adoption Framework (CAF) using PSRule. | [![rules-caf-version-badge]][rules-caf-version-module] [![rules-caf-downloads-badge]][rules-caf-version-module]
+[PSRule.Rules.GitHub]     | A suite of rules to validate GitHub repositories using PSRule. | [![rules-github-version-badge]][rules-github-version-module] [![rules-github-downloads-badge]][rules-github-version-module]
+[PSRule.Rules.MSFT.OSS]   | A suite of rules to validate repositories against Microsoft Open Source Software (OSS) requirements. | [![rules-msft-oss-version-badge]][rules-msft-oss-version-module] [![rules-msft-oss-downloads-badge]][rules-msft-oss-version-module]
+
+[rules-azure-version-badge]: https://img.shields.io/powershellgallery/v/PSRule.Rules.Azure.svg?label=PowerShell%20Gallery&color=brightgreen
+[rules-azure-downloads-badge]: https://img.shields.io/powershellgallery/dt/PSRule.Rules.Azure.svg?color=brightgreen
+[rules-azure-version-module]: https://www.powershellgallery.com/packages/PSRule.Rules.Azure
+[rules-kubernetes-version-badge]: https://img.shields.io/powershellgallery/v/PSRule.Rules.Kubernetes.svg?label=PowerShell%20Gallery&color=brightgreen
+[rules-kubernetes-downloads-badge]: https://img.shields.io/powershellgallery/dt/PSRule.Rules.Kubernetes.svg?color=brightgreen
+[rules-kubernetes-version-module]: https://www.powershellgallery.com/packages/PSRule.Rules.Kubernetes
+[rules-caf-version-badge]: https://img.shields.io/powershellgallery/v/PSRule.Rules.CAF.svg?label=PowerShell%20Gallery&color=brightgreen
+[rules-caf-downloads-badge]: https://img.shields.io/powershellgallery/dt/PSRule.Rules.CAF.svg?color=brightgreen
+[rules-caf-version-module]: https://www.powershellgallery.com/packages/PSRule.Rules.CAF
+[rules-github-version-badge]: https://img.shields.io/powershellgallery/v/PSRule.Rules.GitHub.svg?label=PowerShell%20Gallery&color=brightgreen
+[rules-github-downloads-badge]: https://img.shields.io/powershellgallery/dt/PSRule.Rules.GitHub.svg?color=brightgreen
+[rules-github-version-module]: https://www.powershellgallery.com/packages/PSRule.Rules.GitHub
+[rules-msft-oss-version-badge]: https://img.shields.io/powershellgallery/v/PSRule.Rules.MSFT.OSS.svg?label=PowerShell%20Gallery&color=brightgreen
+[rules-msft-oss-downloads-badge]: https://img.shields.io/powershellgallery/dt/PSRule.Rules.MSFT.OSS.svg?color=brightgreen
+[rules-msft-oss-version-module]: https://www.powershellgallery.com/packages/PSRule.Rules.MSFT.OSS
+[PSRule.Rules.Azure]: https://aka.ms/ps-rule-azure
+[PSRule.Rules.Kubernetes]: https://github.com/microsoft/PSRule.Rules.Kubernetes
+[PSRule.Rules.CAF]: https://github.com/microsoft/PSRule.Rules.CAF
+[PSRule.Rules.GitHub]: https://github.com/microsoft/PSRule.Rules.GitHub
+[PSRule.Rules.MSFT.OSS]: https://github.com/microsoft/PSRule.Rules.MSFT.OSS

docs/scenarios/rule-module/rule-module.md → docs/authoring/packaging-rules.md

@@ -97,30 +97,32 @@ The name of the `ModuleConfig` must match the name of the module.
 Additional `ModuleConfig` resources or with an alternative name are ignored.
 PSRule does not support module configurations distributed outside of a module.
 
-```yaml
----
-# Synopsis: Example module configuration for Enterprise.Rules module.
-apiVersion: github.com/microsoft/PSRule/v1
-kind: ModuleConfig
-metadata:
-  name: Enterprise.Rules
-spec:
-  binding:
-    targetName:
-    - ResourceName
-    - FullName
-    - name
-    targetType:
-    - ResourceType
-    - type
-    - Extension
-    field:
-      resourceId: [ 'ResourceId' ]
-      subscriptionId: [ 'SubscriptionId' ]
-      resourceGroupName: [ 'ResourceGroupName' ]
-  rule:
-    baseline: Enterprise.Default
-```
+!!! Example
+
+    ```yaml
+    ---
+    # Synopsis: Example module configuration for Enterprise.Rules module.
+    apiVersion: github.com/microsoft/PSRule/v1
+    kind: ModuleConfig
+    metadata:
+      name: Enterprise.Rules
+    spec:
+      binding:
+        targetName:
+        - ResourceName
+        - FullName
+        - name
+        targetType:
+        - ResourceType
+        - type
+        - Extension
+        field:
+          resourceId: [ 'ResourceId' ]
+          subscriptionId: [ 'SubscriptionId' ]
+          resourceGroupName: [ 'ResourceGroupName' ]
+      rule:
+        baseline: Enterprise.Default
+    ```
 
 The following options are allowed within a `ModuleConfig`:
 
@@ -144,32 +146,32 @@ This feature removes the need for users to specify it manually.
 
 To set a default baseline, set the `Rule.Baseline` property of the `ModuleConfig` resource.
 
-For example:
-
-```yaml
----
-# Synopsis: Example module configuration for Enterprise.Rules module.
-apiVersion: github.com/microsoft/PSRule/v1
-kind: ModuleConfig
-metadata:
-  name: Enterprise.Rules
-spec:
-  binding:
-    targetName:
-    - ResourceName
-    - FullName
-    - name
-    targetType:
-    - ResourceType
-    - type
-    - Extension
-    field:
-      resourceId: [ 'ResourceId' ]
-      subscriptionId: [ 'SubscriptionId' ]
-      resourceGroupName: [ 'ResourceGroupName' ]
-  rule:
-    baseline: Enterprise.Default
-```
+!!! Example
+
+    ```yaml
+    ---
+    # Synopsis: Example module configuration for Enterprise.Rules module.
+    apiVersion: github.com/microsoft/PSRule/v1
+    kind: ModuleConfig
+    metadata:
+      name: Enterprise.Rules
+    spec:
+      binding:
+        targetName:
+        - ResourceName
+        - FullName
+        - name
+        targetType:
+        - ResourceType
+        - type
+        - Extension
+        field:
+          resourceId: [ 'ResourceId' ]
+          subscriptionId: [ 'SubscriptionId' ]
+          resourceGroupName: [ 'ResourceGroupName' ]
+      rule:
+        baseline: Enterprise.Default
+    ```
 
 This examples set the default baseline to `Enterprise.Default`.
 The default baseline must be included in file ending with `.Rule.yaml` within the module directory structure.
@@ -209,6 +211,6 @@ For example:
 
 ## More information
 
-- [Enterprise.Rules.psd1](Enterprise.Rules/Enterprise.Rules.psd1) - An example module manifest.
-- [Baseline.Rule.yaml](Enterprise.Rules/rules/Baseline.Rule.yaml) - An example baseline.
-- [Config.Rule.yaml](Enterprise.Rules/rules/Config.Rule.yaml) - An example module configuration.
+- [Enterprise.Rules.psd1](packaging-rules/Enterprise.Rules/Enterprise.Rules.psd1) - An example module manifest.
+- [Baseline.Rule.yaml](packaging-rules/Enterprise.Rules/rules/Baseline.Rule.yaml) - An example baseline.
+- [Config.Rule.yaml](packaging-rules/Enterprise.Rules/rules/Config.Rule.yaml) - An example module configuration.

docs/authoring/storing-rules.md

@@ -0,0 +1,58 @@
+---
+author: BernieWhite
+---
+
+# Storing and naming rules
+
+Rules are stored in one or more files and each file can contain one or many rules.
+Additionally, rules can be grouped into a module and distributed.
+
+!!! Abstract
+    This topic covers recommendations for naming and storing rules.
+
+## Using a standard file path
+
+Rules can be standalone or packaged within a module.
+Standalone rules are ideal for a single project such as an Infrastructure as Code (IaC) repository.
+To reuse rules across multiple projects consider packaging these as a module.
+
+The instructions for packaging rules in a module can be found here:
+
+- [Packaging rules in a module](packaging-rules.md)
+
+To store standalone rules we recommend that you:
+
+- **Use .ps-rule/** — Create a sub-directory called `.ps-rule` in the root of your repository.
+  Use all lower-case in the sub-directory name.
+  Put any custom rules within this sub-directory.
+- **Use files ending with .Rule.\*** — PSRule uses a file naming convention to discover rules.
+  Use one of the following depending on the file format you are using:
+  - YAML - `.Rule.yaml`.
+  - JSON - `.Rule.jsonc` or `.Rule.json`.
+  - PowerShell - `.Rule.ps1`.
+
+!!! Note
+    Build pipelines are often case-sensitive or run on Linux-based systems.
+    Using the casing rule above reduces confusion latter when you configure continuous integration (CI).
+
+## Naming rules
+
+When running PSRule, rule names must be unique.
+For example, [PSRule for Azure][1] uses the name prefix of `Azure.` for rules included in the module.
+
+!!! Example
+    The following names are examples of rules included within PSRule for Azure:
+
+    - `Azure.AKS.Version`
+    - `Azure.AKS.AuthorizedIPs`
+    - `Azure.SQL.MinTLS`
+
+When naming custom rules we recommend that you:
+
+- **Use a standard prefix** — You can use the `Local.` or `Org.` prefix for standalone rules.
+  - Alternatively choose a short prefix that identifies your organization.
+- **Use dotted notation** — Use dots to separate rule name.
+- **Use a maximum length of 35 characters** — The default view of `Invoke-PSRule` truncates longer names.
+  PSRule supports longer rule names however if `Invoke-PSRule` is called directly consider using `Format-List`.
+
+  [1]: https://aka.ms/ps-rule-azure

docs/scenarios/rule-docs/rule-docs.md → docs/authoring/writing-rule-help.md

@@ -382,7 +382,7 @@ Module file structure:
 
 ## More information
 
-- [kubernetes.Rule.ps1](kubernetes.Rule.ps1) - An example rule for validating name label.
-- [metadata.Name](en-US/metadata.Name.md) - An example markdown documentation file.
+- [kubernetes.Rule.ps1](writing-rule-help/kubernetes.Rule.ps1) - An example rule for validating name label.
+- [metadata.Name](writing-rule-help/en-US/metadata.Name.md) - An example markdown documentation file.
 
 [extension]: https://marketplace.visualstudio.com/items?itemName=bewhite.psrule-vscode-preview