Add support for AVM references (#2794)

CONTRIBUTING.md

@@ -71,7 +71,8 @@ Rule documentation requires the following annotations for use with PSRule for Az
   
   Available severities are:
   - `Critical` - A 'must have' if the solution is to be considered 'fit for purpose', secure, well governed and managed inline with the Microsoft Azure [Well-Architected Framework](https://learn.microsoft.com/azure/well-architected/).
-  - `Important` - A 'to be considered' within the context of the solution and domain. In some cases, can introduce cost or complexity that should be considered as a trade off and explicity documented as a [Key Design Decision](https://learn.microsoft.com/azure/cloud-adoption-framework/decision-guides/).
+  - `Important` - A 'to be considered' within the context of the solution and domain.
+    In some cases, can introduce cost or complexity that should be considered as a trade off and explicitly documented as a [Key Design Decision](https://learn.microsoft.com/azure/cloud-adoption-framework/decision-guides/).
   - `Awareness` - A 'good to have' feature, normally reserved for solutions with the highest [non-functional requirements](https://learn.microsoft.com/azure/well-architected/reliability/checklist).
   
 - `pillar` - A Azure Well-Architected Framework pillar.
@@ -83,16 +84,21 @@ Rule documentation requires the following annotations for use with PSRule for Az
 
 When authoring and improving rule documentation, please follow these guidelines:
 
-- Provide documentation links to the Azure service and Well-Architected Framework pillar.
+- **Reference the WAF** — by the pillar recommendation.
+  For example if the rule relates to redundancy in the Reliability pillar you could reference [RE:05 Redundancy](https://learn.microsoft.com/azure/well-architected/reliability/redundancy).
+- **Add relevant links** — to the Azure service documentation.
   Examples of good documentation links include:
   - Best practices for the Azure service.
   - Instructions on how to configure the Azure service.
   - [Azure deployment reference](https://learn.microsoft.com/azure/templates/).
-- For links to _https://learn.microsoft.com/_ remove culture from path to make it more generic.
+- **Remove culture** — from links to _https://learn.microsoft.com/_ to make it more generic.
+  This will allow the link to redirect to a language based on the user's settings.
   For example _https://learn.microsoft.com/azure/aks/concepts-scale_ instead of _https://learn.microsoft.com/en-us/azure/aks/concepts-scale_.
-- Add examples of a Azure resource that would pass the rule.
-  At a minimum where applicable provide an example of a Azure template resource.
-  Also consider including example Bicep code.
+- **Add examples** — of a Azure resource that would pass the rule.
+  For rules that apply to pre-flight checks provide an example in Azure Bicep _and_ Azure template format.
+  - Additionally if a pre-built Azure Verified Module is available, reference after the Bicep example using a short-code.
+    The short-code format is `<!-- external:avm <module_path> <params> -->`.
+    For more information see the [example](https://github.com/Azure/PSRule.Rules.Azure/blob/9bb5589bd1ddb01197866d5199f3954cf6f9206b/docs/en/rules/Azure.ContainerApp.MinReplicas.md?plain=1#L113).
 
   [4]: https://microsoft.github.io/PSRule/latest/authoring/writing-rule-help/#writing-markdown-documentation
 

docs/en/rules/Azure.EventGrid.DisableLocalAuth.md

@@ -76,6 +76,8 @@ resource eventGrid 'Microsoft.EventGrid/topics@2022-06-15' = {
 }
 ```
 
+<!-- external:avm avm/res/event-grid/topic disableLocalAuth -->
+
 ### Configure with Azure Policy
 
 To address this issue at runtime use the following policies:

docs/en/rules/Azure.EventGrid.ManagedIdentity.md

@@ -75,6 +75,8 @@ resource eventGrid 'Microsoft.EventGrid/topics@2022-06-15' = {
 }
 ```
 
+<!-- external:avm avm/res/event-grid/topic managedIdentities -->
+
 ## LINKS
 
 - [SE:05 Identity and access management](https://learn.microsoft.com/azure/well-architected/security/identity-access)

docs/en/rules/Azure.EventGrid.TopicPublicAccess.md

@@ -73,6 +73,8 @@ resource eventGrid 'Microsoft.EventGrid/topics@2022-06-15' = {
 }
 ```
 
+<!-- external:avm avm/res/event-grid/topic publicNetworkAccess -->
+
 ## LINKS
 
 - [SE:06 Network controls](https://learn.microsoft.com/azure/well-architected/security/networking)

docs/hooks/shortcodes.py

@@ -49,6 +49,24 @@ def module(markdown: str, page: Page, config: MkDocsConfig, files: Files) -> str
         replace, markdown, flags = re.I | re.M
     )
 
+def external(markdown: str, page: Page, config: MkDocsConfig, files: Files) -> str:
+    '''Replace external shortcodes in markdown.'''
+
+    # Callback for regular expression replacement.
+    def replace(match: re.Match) -> str:
+        type, args = match.groups()
+        args = args.strip()
+        if type == "avm":
+            return _external_reference_avm(args)
+
+        raise RuntimeError(f"Unknown shortcode external:{type}")
+
+    # Replace external shortcodes.
+    return re.sub(
+        r"<!-- external:(\w+)(.*?) -->",
+        replace, markdown, flags = re.I | re.M
+    )
+
 def _relative_uri(path: str, page: Page, files: Files) -> str:
     '''Get relative URI for a file including anchor.'''
 
@@ -120,3 +138,20 @@ def _badge_for_configuration(text: str, page: Page, files: Files) -> str:
         icon = f"[:{icon}:]({href} 'Applies to configuration setting')",
         text = f"[{text}]({href})"
     )
+
+def _reference_block(style: str, title: str, text: str = "") -> str:
+    '''Add an external reference block.'''
+
+    lines = text.replace('\r\n', '\n').replace('\r', '\n').replace('\n', '\n    ').strip()
+    return f"!!! {style} \"{title}\"\n    {lines}"
+
+def _external_reference_avm(text: str) -> str:
+    '''Create a reference to AVM.'''
+
+    avm_path = text.split(' ')[0]
+
+    return _reference_block(
+        style = "Example",
+        title = f"Configure with [Azure Verified Modules](https://github.com/Azure/bicep-registry-modules/tree/main/{avm_path})",
+        text = f"A pre-built module is avilable on the Azure Bicep public registry.\nTo reference the module, please use the following syntax: `br/public:{avm_path}:<version>`"
+    )