Added support for custom configuration #121

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+What's changed since v0.7.0:
+
+- Engine features:
+  - Added support for custom configuration key values. [#121](https://github.com/BernieWhite/PSDocs/issues/121)
+    - See `about_PSDocs_Configuration` for more details.
+
 ## v0.7.0
 
 What's changed since v0.6.3:

README.md

@@ -117,7 +117,9 @@ The following commands exist in the `PSDocs.Dsc` module:
 
 The following conceptual topics exist in the `PSDocs` module:
 
+- [Configuration](docs/concepts/PSDocs/en-US/about_PSDocs_Configuration.md)
 - [Options](docs/concepts/PSDocs/en-US/about_PSDocs_Options.md)
+  - [Configuration](docs/concepts/PSDocs/en-US/about_PSDocs_Options.md#configuration)
   - [Execution.LanguageMode](docs/concepts/PSDocs/en-US/about_PSDocs_Options.md#executionlanguagemode)
   - [Markdown.ColumnPadding](docs/concepts/PSDocs/en-US/about_PSDocs_Options.md#markdowncolumnpadding)
   - [Markdown.Encoding](docs/concepts/PSDocs/en-US/about_PSDocs_Options.md#markdownencoding)

docs/concepts/PSDocs/en-US/about_PSDocs_Configuration.md

@@ -0,0 +1,97 @@
+# PSDocs_Configuration
+
+## about_PSDocs_Configuration
+
+## SHORT DESCRIPTION
+
+Describes custom configuration that can be used within PSDocs document definitions.
+
+## LONG DESCRIPTION
+
+PSDocs lets you generate dynamic markdown documents using PowerShell blocks known as document definitions.
+Document definitions can read custom configuration set at runtime or within options to change rendering.
+Within a document definition, PSDocs exposes custom configuration through the `$PSDocs` automatic variable.
+
+### Setting configuration
+
+To specify custom configuration, set a property of the `configuration` object.
+Configuration can be set at runtime or as YAML by configuring `ps-docs.yaml`.
+
+For example:
+
+```yaml
+# Example: ps-docs.yaml
+
+# YAML: Using the configuration YAML property to set custom configuration 'MODULE1_KEY1'
+configuration:
+  MODULE1_KEY1: Value1
+```
+
+To ensure each custom key is unique use a prefix followed by an underscore that represent your module.
+Key names are not case sensitive, however we recommend you use uppercase for consistency.
+
+### Reading configuration
+
+The `$PSDocs` automatic variable can be used within a Document definition to read configuration.
+Each custom configuration key is available under the `.Configuration` property.
+Additionally, several helper methods are available for advanced usage.
+
+Syntax:
+
+```powershell
+$PSDocs.Configuration.<configurationKey>
+```
+
+For example:
+
+```powershell
+# Get the value of the custom configuration 'MODULE1_KEY1'
+$PSDocs.Configuration.MODULE1_KEY1
+```
+
+The following helper methods are available:
+
+- `GetStringValues(string configurationKey)` - The configuration value as an array of strings.
+This helper will always returns an array of strings.
+The array will be empty if the configuration key is not defined or empty.
+- `GetValueOrDefault(string configurationKey, object defaultValue)` - Returns the configuration value.
+When the configuration key is not defined the default value will be used instead.
+- `GetBoolOrDefault(string configurationKey, bool defaultValue)` - The configuration value as a boolean.
+When the configuration key is not defined the default value will be used instead.
+
+Syntax:
+
+```powershell
+$PSDocs.Configuration.helper()
+```
+
+For example:
+
+```powershell
+# Example using GetStringValues
+$values = $PSDocs.Configuration.GetStringValues('SAMPLE_AUTHORS');
+
+# Example using GetValueOrDefault
+$value = $PSDocs.Configuration.GetValueOrDefault('SAMPLE_CONTENT_OWNER', 'defaultUser');
+
+# Example using GetBoolOrDefault
+if ($PSDocs.Configuration.GetBoolOrDefault('SAMPLE_USE_PARAMETERS_SNIPPET', $True)) {
+    # Execute code
+}
+```
+
+## NOTE
+
+An online version of this document is available at https://github.com/BernieWhite/PSDocs/blob/main/docs/concepts/PSDocs/en-US/about_PSDocs_Configuration.md.
+
+## SEE ALSO
+
+- [Invoke-PSDocument](https://github.com/BernieWhite/PSDocs/blob/main/docs/commands/PSDocs/en-US/Invoke-PSDocument.md)
+
+## KEYWORDS
+
+- Configuration
+- PSDocs
+- GetStringValues
+- GetValueOrDefault
+- GetBoolOrDefault

docs/concepts/PSDocs/en-US/about_PSDocs_Options.md

@@ -13,6 +13,7 @@ This topic describes what options are available, when to and how to use them.
 
 The following workspace options are available for use:
 
+- [Configuration](#configuration)
 - [Execution.LanguageMode](#executionlanguagemode)
 - [Markdown.ColumnPadding](#markdowncolumnpadding)
 - [Markdown.Encoding](#markdownencoding)
@@ -62,6 +63,28 @@ For example:
 Invoke-PSDocument -Path . -Option '.\myconfig.yml'.
 ```
 
+### Configuration
+
+Sets custom configuration for document generation.
+Document definitions may allow custom configuration to be specified.
+To specify custom configuration, set a property of the configuration object.
+
+To ensure each custom key is unique use a prefix followed by an underscore that represent your module.
+Key names are not case sensitive, however we recommend you use uppercase for consistency.
+
+This option can be specified using:
+
+```powershell
+# PowerShell: Using the Configuration hashtable key to set custom configuration 'MODULE1_KEY1'
+$option = New-PSDocumentOption -Option @{ 'Configuration.MODULE1_KEY1' = 'Value1' }
+```
+
+```yaml
+# YAML: Using the configuration YAML property to set custom configuration 'MODULE2_KEY1'
+configuration:
+  MODULE2_KEY1: Value1
+```
+
 ### Execution.LanguageMode
 
 Unless PowerShell has been constrained, full language features of PowerShell are available to use within document definitions.
@@ -143,7 +166,8 @@ markdown:
 
 ### Markdown.Encoding
 
-Sets the text encoding used for markdown output files. One of the following values can be used:
+Sets the text encoding used for markdown output files.
+One of the following values can be used:
 
 - Default
 - UTF8
@@ -315,14 +339,19 @@ output:
 ### Example ps-docs.yaml
 
 ```yaml
-# Set markdown options
+configuration:
+  SAMPLE_USE_PARAMETERS_SNIPPET: true
+
 execution:
   languageMode: ConstrainedLanguage
+
+# Set markdown options
 markdown:
   # Use UTF-8 with BOM
   encoding: UTF8
   skipEmptySections: false
   wrapSeparator: '\'
+
 output:
   culture:
   - 'en-US'
@@ -334,14 +363,18 @@ output:
 ```yaml
 # These are the default options.
 # Only properties that differ from the default values need to be specified.
+configuration: { }
+
 execution:
   languageMode: FullLanguage
+
 markdown:
   encoding: Default
   skipEmptySections: true
   wrapSeparator: ' '
   columnPadding: MatchHeader
   useEdgePipes: WhenRequired
+
 output:
   culture: [ ]
   path: null
@@ -358,6 +391,9 @@ An online version of this document is available at https://github.com/BernieWhit
 
 ## KEYWORDS
 
+- Configuration
 - Options
 - Markdown
 - PSDocument
+- Output
+- Execution

docs/concepts/PSDocs/en-US/about_PSDocs_Variables.md

@@ -11,7 +11,7 @@ Describes the automatic variables that can be used within PSDocs document defini
 PSDocs lets you generate dynamic markdown documents using PowerShell blocks.
 To generate markdown, a document is defined inline or within script files by using the `document` keyword.
 
-Within a document definition, PSDocs exposes a number of automatic variables that can be read to assist with dynamic document generation.
+Within a document definition, PSDocs exposes several automatic variables that can be read to assist with dynamic document generation.
 Overwriting these variables or variable properties is not supported.
 
 The following variables are available for use:
@@ -20,6 +20,7 @@ The following variables are available for use:
 - [$Document](#document)
 - [$InstanceName](#instancename)
 - [$LocalizedData](#localizeddata)
+- [$PSDocs](#psdocs)
 - [$TargetObject](#targetobject)
 - [$Section](#section)
 
@@ -134,6 +135,42 @@ This document returns content similar to:
 Localized string for en-ZZ. Format=TestType.
 ```
 
+### PSDocs
+
+An object representing the current context of PSDocs.
+
+In addition, `$PSDocs` provides several helper properties and functions.
+
+The following properties are available for public read access:
+
+- `Configuration` - An object with custom configuration properties.
+Each configuration key specified in `ps-docs.yaml` is assessable as a property.
+Additionally helper methods can be used.
+See `about_PSDocs_Configuration` for more information.
+- `Culture` - The name of the culture currently being processed.
+- `TargetObject` - The value of the pipeline object currently being processed.
+
+Syntax:
+
+```powershell
+$PSDocs
+```
+
+```powershell
+# Get the value of the custom configuration 'Key1'
+$PSDocs.Configuration.Key1
+```
+
+```powershell
+# Return the currently processed culture. e.g. 'en-US'
+$PSDocs.Culture
+```
+
+```powershell
+# Return the current pipeline object.
+$PSDocs.TargetObject
+```
+
 ### TargetObject
 
 The value of the pipeline object currently being processed.
@@ -196,5 +233,6 @@ An online version of this document is available at https://github.com/BernieWhit
 - Culture
 - Document
 - InstanceName
-- InputObject
+- PSDocs
+- TargetObject
 - Section

src/PSDocs/Common/DictionaryExtensions.cs

@@ -3,7 +3,6 @@
 using System.Collections.Generic;
 using System.Diagnostics;
 using System.Linq;
-using System.Management.Automation;
 
 namespace PSDocs
 {
@@ -77,9 +76,14 @@ public static bool TryGetBool(this IDictionary<string, object> dictionary, strin
         [DebuggerStepThrough]
         public static void AddUnique(this IDictionary<string, object> dictionary, IEnumerable<KeyValuePair<string, object>> values)
         {
+            if (values == null)
+                return;
+
             foreach (var kv in values)
+            {
                 if (!dictionary.ContainsKey(kv.Key))
                     dictionary.Add(kv.Key, kv.Value);
+            }
         }
     }
 }

src/PSDocs/Configuration/ConfigurationOption.cs

@@ -0,0 +1,40 @@
+
+using System.Collections;
+using System.Collections.Generic;
+
+namespace PSDocs.Configuration
+{
+    /// <summary>
+    /// A set of custom configuration values that are exposed at runtime.
+    /// </summary>
+    public sealed class ConfigurationOption : KeyMapDictionary<object>
+    {
+        private const string KEYMAP_PREFIX = "Configuration.";
+
+        public ConfigurationOption()
+            : base() { }
+
+        public ConfigurationOption(ConfigurationOption option)
+            : base(option) { }
+
+        private ConfigurationOption(Hashtable hashtable)
+            : base(hashtable) { }
+
+        public static implicit operator ConfigurationOption(Hashtable hashtable)
+        {
+            return new ConfigurationOption(hashtable);
+        }
+
+        internal static ConfigurationOption Combine(ConfigurationOption o1, ConfigurationOption o2)
+        {
+            var result = new ConfigurationOption(o1);
+            result.AddUnique(o2);
+            return result;
+        }
+
+        internal void Load(IDictionary<string, object> dictionary)
+        {
+            Load(KEYMAP_PREFIX, dictionary);
+        }
+    }
+}