Snippet improvements #84 #94 #95 #96 (#97)

Author: BernieWhite

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+What's changed since pre-release v0.4.0-B2107004:
+
+- General improvements:
+  - Secret string parameters now include an example Key Vault reference. [#94](https://github.com/Azure/PSDocs.Azure/issues/94)
+  - Improved output of parameter object default values. [#84](https://github.com/Azure/PSDocs.Azure/issues/84)
+    - Default values and allowed values now appear in a code block.
+  - Allow optional parameters to be skipped in snippet. [#96](https://github.com/Azure/PSDocs.Azure/issues/96)
+    - To exclude optional parameters from snippets configure `AZURE_SNIPPET_SKIP_OPTIONAL_PARAMETER`.
+    - See [about_PSDocs_Azure_Configuration] for details.
+- Bug fixes:
+  - Ignore function default values in snippets. [#95](https://github.com/Azure/PSDocs.Azure/issues/95)
+    - To include parameters using a function default value configure `AZURE_SNIPPET_SKIP_DEFAULT_VALUE_FN`.
+    - See [about_PSDocs_Azure_Configuration] for details.
+
 ## v0.4.0-B2107004 (pre-release)
 
 What's changed since v0.3.0:

README.md

@@ -290,6 +290,8 @@ The following conceptual topics exist in the `PSDocs.Azure` module:
 
 - [Badges](docs/concepts/en-US/about_PSDocs_Azure_Badges.md)
 - [Configuration](docs/concepts/en-US/about_PSDocs_Azure_Configuration.md)
+  - [AZURE_SNIPPET_SKIP_DEFAULT_VALUE_FN](docs/concepts/en-US/about_PSDocs_Azure_Configuration.md#azure_snippet_skip_default_value_fn)
+  - [AZURE_SNIPPET_SKIP_OPTIONAL_PARAMETER](docs/concepts/en-US/about_PSDocs_Azure_Configuration.md#azure_snippet_skip_optional_parameter)
   - [AZURE_USE_PARAMETER_FILE_SNIPPET](docs/concepts/en-US/about_PSDocs_Azure_Configuration.md#azure_use_parameter_file_snippet)
   - [AZURE_USE_COMMAND_LINE_SNIPPET](docs/concepts/en-US/about_PSDocs_Azure_Configuration.md#azure_use_command_line_snippet)
 - [Conventions](docs/concepts/en-US/about_PSDocs_Azure_Conventions.md)

docs/concepts/en-US/about_PSDocs_Azure_Configuration.md

@@ -17,9 +17,69 @@ For details of setting configuration options see [PSDocs options][options]
 
 The following configurations options are available for use:
 
+- [AZURE_SNIPPET_SKIP_DEFAULT_VALUE_FN](#azure_snippet_skip_default_value_fn)
+- [AZURE_SNIPPET_SKIP_OPTIONAL_PARAMETER](#azure_snippet_skip_optional_parameter)
 - [AZURE_USE_PARAMETER_FILE_SNIPPET](#azure_use_parameter_file_snippet)
 - [AZURE_USE_COMMAND_LINE_SNIPPET](#azure_use_command_line_snippet)
 
+### AZURE_SNIPPET_SKIP_DEFAULT_VALUE_FN
+
+This configuration option determines if parameters with a function defaultValue are included in snippets.
+By default, a parameters with a function default value are not included in snippets.
+i.e. If a parameter default value is set to `[resourceGroup.location]` it is not included in snippets.
+
+Syntax:
+
+```yaml
+configuration:
+  AZURE_SNIPPET_SKIP_DEFAULT_VALUE_FN: bool # Either true or false
+```
+
+Default:
+
+```yaml
+# YAML: The default AZURE_SNIPPET_SKIP_DEFAULT_VALUE_FN configuration option
+configuration:
+  AZURE_SNIPPET_SKIP_DEFAULT_VALUE_FN: true
+```
+
+Example:
+
+```yaml
+# YAML: Include parameters with a function default value in snippets.
+configuration:
+  AZURE_SNIPPET_SKIP_DEFAULT_VALUE_FN: false
+```
+
+### AZURE_SNIPPET_SKIP_OPTIONAL_PARAMETER
+
+This configuration option determines optional parameters are included in snippets.
+By default, optional parameters are included in snippets.
+To ignore optional parameter, set this option to `false`.
+
+Syntax:
+
+```yaml
+configuration:
+  AZURE_SNIPPET_SKIP_OPTIONAL_PARAMETER: bool # Either true or false
+```
+
+Default:
+
+```yaml
+# YAML: The default AZURE_SNIPPET_SKIP_OPTIONAL_PARAMETER configuration option
+configuration:
+  AZURE_SNIPPET_SKIP_OPTIONAL_PARAMETER: false
+```
+
+Example:
+
+```yaml
+# YAML: Do not include optional parameters in snippets
+configuration:
+  AZURE_SNIPPET_SKIP_OPTIONAL_PARAMETER: true
+```
+
 ### AZURE_USE_PARAMETER_FILE_SNIPPET
 
 This configuration option determines if a parameter file snippet is added to documentation.
@@ -49,7 +109,6 @@ configuration:
   AZURE_USE_PARAMETER_FILE_SNIPPET: false
 ```
 
-
 ### AZURE_USE_COMMAND_LINE_SNIPPET
 
 This configuration option determines if a command line snippet is added to documentation.

docs/setup/configuring-options.md

@@ -0,0 +1,29 @@
+# Configuring options
+
+PSDocs for Azure comes with many configuration options.
+Additionally, the PSDocs engine includes several options that apply to all rules.
+You can visit the [about_PSDocs_Options][1] topic to read about general PSDocs options.
+
+  [1]: https://github.com/microsoft/PSDocs/blob/main/docs/concepts/PSDocs/en-US/about_PSDocs_Options.md
+
+## Setting options
+
+Configuration options are set within the `ps-docs.yaml` file.
+If you don't already have a `ps-docs.yaml` file you can create one in the root of your repository.
+
+Configuration can be combined as indented keys.
+Use comments to add context.
+Here are some examples:
+
+```yaml
+configuration:
+  # Show command line snippet
+  AZURE_USE_COMMAND_LINE_SNIPPET: true
+
+  # Hide parameter file snippet
+  AZURE_PARAMETER_FILE_EXPANSION: false
+```
+
+!!! Tip
+    YAML can be a bit particular about indenting.
+    If something is not working, double check that you have consistent spacing in your options file.

docs/setup/configuring-snippets.md

@@ -0,0 +1,136 @@
+# Configuring snippets
+
+PSDocs for Azure supports a number of snippets that can be included in documentation.
+This feature can be enabled by using the following configuration options.
+
+## Configuration
+
+!!! Tip
+    Each of these configuration options are set within the `ps-docs.yaml` file.
+    To learn how to set configuration options see [Configuring options][1].
+
+  [1]: configuring-options.md
+
+### Skip function default value parameters
+
+:octicons-milestone-24: v0.4.0
+
+This configuration option determines if parameters with a function defaultValue are included in snippets.
+By default, a parameters with a function default value are not included in snippets.
+i.e. If a parameter default value is set to `[resourceGroup.location]` it is not included in snippets.
+
+Syntax:
+
+```yaml
+configuration:
+  AZURE_SNIPPET_SKIP_DEFAULT_VALUE_FN: bool # Either true or false
+```
+
+Default:
+
+```yaml
+# YAML: The default AZURE_SNIPPET_SKIP_DEFAULT_VALUE_FN configuration option
+configuration:
+  AZURE_SNIPPET_SKIP_DEFAULT_VALUE_FN: true
+```
+
+Example:
+
+```yaml
+# YAML: Include parameters with a function default value in snippets.
+configuration:
+  AZURE_SNIPPET_SKIP_DEFAULT_VALUE_FN: false
+```
+
+### Skip optional parameters
+
+:octicons-milestone-24: v0.4.0
+
+This configuration option determines optional parameters are included in snippets.
+By default, optional parameters are included in snippets.
+To ignore optional parameter, set this option to `false`.
+
+Syntax:
+
+```yaml
+configuration:
+  AZURE_SNIPPET_SKIP_OPTIONAL_PARAMETER: bool # Either true or false
+```
+
+Default:
+
+```yaml
+# YAML: The default AZURE_SNIPPET_SKIP_OPTIONAL_PARAMETER configuration option
+configuration:
+  AZURE_SNIPPET_SKIP_OPTIONAL_PARAMETER: false
+```
+
+Example:
+
+```yaml
+# YAML: Do not include optional parameters in snippets
+configuration:
+  AZURE_SNIPPET_SKIP_OPTIONAL_PARAMETER: true
+```
+
+### Parameter file snippet
+
+:octicons-milestone-24: v0.2.0
+
+This configuration option determines if a parameter file snippet is added to documentation.
+By default, a snippet is generated.
+To prevent a parameter file snippet being generated, set this option to `false`.
+
+Syntax:
+
+```yaml
+configuration:
+  AZURE_USE_PARAMETER_FILE_SNIPPET: bool
+```
+
+Default:
+
+```yaml
+# YAML: The default AZURE_USE_PARAMETER_FILE_SNIPPET configuration option
+configuration:
+  AZURE_USE_PARAMETER_FILE_SNIPPET: false
+```
+
+Example:
+
+```yaml
+# YAML: Set the AZURE_USE_PARAMETER_FILE_SNIPPET configuration option to enable expansion
+configuration:
+  AZURE_USE_PARAMETER_FILE_SNIPPET: true
+```
+
+### Command line snippet
+
+:octicons-milestone-24: v0.2.0
+
+This configuration option determines if a command line snippet is added to documentation.
+By default, this command line snippet is not generated.
+To generate command line snippet, set this option to `true`.
+
+Syntax:
+
+```yaml
+configuration:
+  AZURE_USE_COMMAND_LINE_SNIPPET: bool # Either true or false
+```
+
+Default:
+
+```yaml
+# YAML: The default AZURE_USE_COMMAND_LINE_SNIPPET configuration option is to disable generation
+configuration:
+  AZURE_USE_COMMAND_LINE_SNIPPET: false
+```
+
+Example:
+
+```yaml
+# YAML: To enable command line snippet
+configuration:
+  AZURE_USE_COMMAND_LINE_SNIPPET: true
+```

mkdocs.yml

@@ -48,9 +48,9 @@ nav:
     - Releases:
       - Change log: https://github.com/Azure/PSDocs.Azure/blob/main/CHANGELOG.md
     - Support: support.md
-  # - Setup:
-  #   - Configuring options: setup/configuring-options.md
-  #   - Configuring rule defaults: setup/configuring-rules.md
+  - Setup:
+    - Configuring options: setup/configuring-options.md
+    - Configuring snippets: setup/configuring-snippets.md
   #   - Configuring expansion: setup/configuring-expansion.md
 
   #   - Configuration options: concepts/about_PSRule_Azure_Configuration.md