Build: (35e96bd) Elaborate on YAML nesting

Author: astrsh

_sources/config/development/config-data.rst.txt

@@ -357,38 +357,65 @@ Nesting Objects
 Because values in maps and items in lists can be of any type, It's
 possible to nest maps in maps, lists in lists, lists in maps, and so on.
 
-Here is an example of a ``Map`` contained within the value of another
-``Map`` (which is the top level object):
+.. tip::
+
+    Defining something inside something else is commonly referred to as 'nesting'.
 
 .. tab-set::
 
    .. tab-item:: YAML
 
-      .. admonition:: Info
-         :class: tip
+      When setting the value of a map, typically it will just fit on the
+      same line as the key, for example the ``Float`` 42 can just be written
+      in-line with the key, after the colon like so:
+
+      .. code-block:: yaml
 
-         For simple data types like integers and strings it is clear which key
-         corresponds to which value, as they are typically contained on the same
-         line, but maps and lists may span multiple lines, so we need a way of
-         defining which objects are defined under which keys and items. In YAML,
-         we can specify this kind of relationship via *indentation* - which is
-         simply how many spaces come before the key one a line. We conventionally
-         use two spaces to indicate 'one level' of indentation in YAML configs.
+          key: 42
+
+      Types that can span multiple lines, such as maps and lists won't fit
+      on a single line. For example you man want the following map which spans
+      multiple lines to be a value within another map:
 
       .. code-block:: yaml
-         :caption: config.yml
-         :linenos:
 
-         parent-key:
-           child-key: value
-           sibling-key: another value
+          foo: a
+          bar: b
+
+      To nest this map as a value of a key, say ``baz``, in another map, it can be
+      defined under the key with additional indentation like so:
+
+      .. code-block:: yaml
+
+          baz:
+            foo: a
+            bar: b
+
+      Indentation / indenting text refers to having some consistent number of spaces before
+      each line in text. In YAML, the recommended number of spaces to indent is 2 as shown above.
+
+      Lists can be nested similarly like so:
+
+      .. code-block:: yaml
+
+          my-list:
+            - item 1
+            - item 2
 
-      You can see that the map containing ``child-key`` and ``sibling-key`` is
-      indented by two spaces, and is defined under the ``parent-key`` key,
-      signifying that it belongs to that key.
+      Multiple 'levels of indentation' can be used, for example here is the prior map further
+      nested under (as the value for the key) ``qux``:
+
+      .. code-block:: yaml
+
+          qux:
+            baz:
+              foo: a
+              bar: b
 
    .. tab-item:: JSON
 
+      Example of a ``Map`` defined in a ``Map``:
+
       .. code-block:: json
          :caption: config.json
          :linenos:
@@ -400,36 +427,66 @@ Here is an example of a ``Map`` contained within the value of another
             }
          }
 
-And here is a ``Map`` (the top level object) containing a ``List`` of
-``String``\ s:
-
-.. tab-set::
-
-   .. tab-item:: YAML
-
-      .. code-block:: yaml
-         :caption: config.yml
-         :linenos:
-
-         list of strings:
-           - item 1
-           - item 2
-           - item 3
-
-   .. tab-item:: JSON
+      Example of a ``List`` defined in a ``Map``: 
 
       .. code-block:: json
          :caption: config.json
          :linenos:
-         
+
          {
-            "list of strings": [
-               "item 1",
-               "item 2",
-               "item 3"
+            "my-list": [
+              "item 1",
+              "item 2"
             ]
          }
 
+Illegally defining two values for one key
+-----------------------------------------
+
+A common mistake in YAML is to accidentally assign two different
+values to the same key.
+
+For example the following is invalid:
+
+.. code-block:: yaml
+
+   key: foo
+     baz: bar
+
+The reason this is invalid is because there are two competing values being
+assigned to ``key``, which are ``foo`` and the map containing ``baz: bar``.
+
+Deleting one of the values would make this valid YAML:
+
+.. code-block:: yaml
+
+    key:
+      baz: bar
+
+Or
+
+.. code-block:: yaml
+
+    key: foo
+
+A config might end up in this invalid state for many reasons.
+
+A key may have been deleted or omitted which could be remedied by re-adding it like so:
+
+.. code-block:: yaml
+    
+    key: foo
+    missing:
+      baz: bar
+
+Indentation may have been changed by accident, for example removing indentation 
+would make it valid like so:
+
+.. code-block:: yaml
+    
+    key: foo
+    baz: bar
+
 Combining Everything
 ====================
 

_sources/config/documentation/objects/BiomeColorMapping.rst.txt

@@ -34,10 +34,10 @@ Uses
 
 Used by 2 parameters:
 
-- :ref:`In EXACT in BiomeColorConverter <object-biomecolorconverter-template-biome-provider-image-v2-exact-parameter-match>`:
+- :ref:`In CLOSEST in BiomeColorConverter <object-biomecolorconverter-template-biome-provider-image-v2-closest-parameter-match>`:
 
-  :bdg-ref-primary:`match <object-biomecolorconverter-template-biome-provider-image-v2-exact-parameter-match>` :doc:`/config/documentation/objects/BiomeColorMapping` 
+  :bdg-ref-primary:`match <object-biomecolorconverter-template-biome-provider-image-v2-closest-parameter-match>` :doc:`/config/documentation/objects/BiomeColorMapping` 
 
-- :ref:`In CLOSEST in BiomeColorConverter <object-biomecolorconverter-template-biome-provider-image-v2-closest-parameter-match>`:
+- :ref:`In EXACT in BiomeColorConverter <object-biomecolorconverter-template-biome-provider-image-v2-exact-parameter-match>`:
 
-  :bdg-ref-primary:`match <object-biomecolorconverter-template-biome-provider-image-v2-closest-parameter-match>` :doc:`/config/documentation/objects/BiomeColorMapping` 
+  :bdg-ref-primary:`match <object-biomecolorconverter-template-biome-provider-image-v2-exact-parameter-match>` :doc:`/config/documentation/objects/BiomeColorMapping` 

_sources/config/documentation/objects/BiomeProvider.rst.txt

@@ -132,10 +132,10 @@ Uses
 
 Used by 2 parameters:
 
-- :ref:`In base in pack.yml <config-pack.yml-template-base-base-parameter-biomes>`:
+- :ref:`In EXTRUSION in BiomeProvider <object-biomeprovider-template-biome-provider-extrusion-extrusion-parameter-provider>`:
 
-  :bdg-ref-primary:`biomes <config-pack.yml-template-base-base-parameter-biomes>` :doc:`/config/documentation/objects/BiomeProvider` - Determines where biomes should generate in the world.
+  :bdg-ref-primary:`provider <object-biomeprovider-template-biome-provider-extrusion-extrusion-parameter-provider>` :doc:`/config/documentation/objects/BiomeProvider` 
 
-- :ref:`In EXTRUSION in BiomeProvider <object-biomeprovider-template-biome-provider-extrusion-extrusion-parameter-provider>`:
+- :ref:`In base in pack.yml <config-pack.yml-template-base-base-parameter-biomes>`:
 
-  :bdg-ref-primary:`provider <object-biomeprovider-template-biome-provider-extrusion-extrusion-parameter-provider>` :doc:`/config/documentation/objects/BiomeProvider` 
+  :bdg-ref-primary:`biomes <config-pack.yml-template-base-base-parameter-biomes>` :doc:`/config/documentation/objects/BiomeProvider` - Determines where biomes should generate in the world.

_sources/config/documentation/objects/Block.rst.txt

@@ -14,34 +14,34 @@ Uses
 
 Used by 8 parameters:
 
-- :ref:`In base in ORE <config-ore-template-config-ore-base-parameter-material-overrides>`:
+- :ref:`In base in SCATTERED_ORE <config-scattered_ore-template-config-ore-base-parameter-replace>`:
 
-  :bdg-ref-success:`material-overrides <config-ore-template-config-ore-base-parameter-material-overrides>` :doc:`/config/documentation/objects/Map`\<:doc:`/config/documentation/objects/Block`\, :doc:`/config/documentation/objects/Block`\> 
+  :bdg-ref-primary:`replace <config-scattered_ore-template-config-ore-base-parameter-replace>` :doc:`/config/documentation/objects/Set`\<:doc:`/config/documentation/objects/Block`\> 
 
 - :ref:`In base in SCATTERED_ORE <config-scattered_ore-template-config-ore-base-parameter-material>`:
 
   :bdg-ref-primary:`material <config-scattered_ore-template-config-ore-base-parameter-material>` :doc:`/config/documentation/objects/Block` 
 
-- :ref:`In MATCH in Pattern <object-pattern-template-config-locators-match-parameter-block>`:
-
-  :bdg-ref-primary:`block <object-pattern-template-config-locators-match-parameter-block>` :doc:`/config/documentation/objects/Block` 
-
-- :ref:`In base in SCATTERED_ORE <config-scattered_ore-template-config-ore-base-parameter-material-overrides>`:
+- :ref:`In base in ORE <config-ore-template-config-ore-base-parameter-material>`:
 
-  :bdg-ref-success:`material-overrides <config-scattered_ore-template-config-ore-base-parameter-material-overrides>` :doc:`/config/documentation/objects/Map`\<:doc:`/config/documentation/objects/Block`\, :doc:`/config/documentation/objects/Block`\> 
+  :bdg-ref-primary:`material <config-ore-template-config-ore-base-parameter-material>` :doc:`/config/documentation/objects/Block` 
 
-- :ref:`In base in SCATTERED_ORE <config-scattered_ore-template-config-ore-base-parameter-replace>`:
+- :ref:`In MATCH_SET in Pattern <object-pattern-template-config-locators-match_set-parameter-blocks>`:
 
-  :bdg-ref-primary:`replace <config-scattered_ore-template-config-ore-base-parameter-replace>` :doc:`/config/documentation/objects/Set`\<:doc:`/config/documentation/objects/Block`\> 
+  :bdg-ref-primary:`blocks <object-pattern-template-config-locators-match_set-parameter-blocks>` :doc:`/config/documentation/objects/Set`\<:doc:`/config/documentation/objects/Block`\> 
 
 - :ref:`In base in ORE <config-ore-template-config-ore-base-parameter-replace>`:
 
   :bdg-ref-primary:`replace <config-ore-template-config-ore-base-parameter-replace>` :doc:`/config/documentation/objects/Set`\<:doc:`/config/documentation/objects/Block`\> 
 
-- :ref:`In MATCH_SET in Pattern <object-pattern-template-config-locators-match_set-parameter-blocks>`:
+- :ref:`In base in ORE <config-ore-template-config-ore-base-parameter-material-overrides>`:
 
-  :bdg-ref-primary:`blocks <object-pattern-template-config-locators-match_set-parameter-blocks>` :doc:`/config/documentation/objects/Set`\<:doc:`/config/documentation/objects/Block`\> 
+  :bdg-ref-success:`material-overrides <config-ore-template-config-ore-base-parameter-material-overrides>` :doc:`/config/documentation/objects/Map`\<:doc:`/config/documentation/objects/Block`\, :doc:`/config/documentation/objects/Block`\> 
 
-- :ref:`In base in ORE <config-ore-template-config-ore-base-parameter-material>`:
+- :ref:`In MATCH in Pattern <object-pattern-template-config-locators-match-parameter-block>`:
+
+  :bdg-ref-primary:`block <object-pattern-template-config-locators-match-parameter-block>` :doc:`/config/documentation/objects/Block` 
+
+- :ref:`In base in SCATTERED_ORE <config-scattered_ore-template-config-ore-base-parameter-material-overrides>`:
 
-  :bdg-ref-primary:`material <config-ore-template-config-ore-base-parameter-material>` :doc:`/config/documentation/objects/Block` 
+  :bdg-ref-success:`material-overrides <config-scattered_ore-template-config-ore-base-parameter-material-overrides>` :doc:`/config/documentation/objects/Map`\<:doc:`/config/documentation/objects/Block`\, :doc:`/config/documentation/objects/Block`\> 

_sources/config/documentation/objects/Boolean.rst.txt

@@ -12,46 +12,46 @@ Uses
 
 Used by 13 parameters:
 
-- :ref:`In GABOR in NoiseSampler <object-noisesampler-template-config-noise-function-gabor-parameter-isotropic>`:
-
-  :bdg-ref-success:`isotropic <object-noisesampler-template-config-noise-function-gabor-parameter-isotropic>` :doc:`/config/documentation/objects/Boolean` 
-
-- :ref:`In base in SCATTERED_ORE <config-scattered_ore-template-config-ore-base-parameter-physics>`:
+- :ref:`In CHANNEL in NoiseSampler <object-noisesampler-template-library-image-channel-parameter-normalize>`:
 
-  :bdg-ref-success:`physics <config-scattered_ore-template-config-ore-base-parameter-physics>` :doc:`/config/documentation/objects/Boolean` 
+  :bdg-ref-success:`normalize <object-noisesampler-template-library-image-channel-parameter-normalize>` :doc:`/config/documentation/objects/Boolean` - If the channel should be normalized to range [-1, 1] or not.
 
 - :ref:`In STITCHED_BITMAP in Image <object-image-template-library-image-stitched_bitmap-parameter-zero-indexed>`:
 
   :bdg-ref-success:`zero-indexed <object-image-template-library-image-stitched_bitmap-parameter-zero-indexed>` :doc:`/config/documentation/objects/Boolean` 
 
-- :ref:`In DISTANCE in NoiseSampler <object-noisesampler-template-config-noise-function-distance-parameter-normalize>`:
+- :ref:`In base in SCATTERED_ORE <config-scattered_ore-template-config-ore-base-parameter-physics>`:
 
-  :bdg-ref-success:`normalize <object-noisesampler-template-config-noise-function-distance-parameter-normalize>` :doc:`/config/documentation/objects/Boolean` - If set to true, the returned distance will be normalized to be within the range ``[-1, 1]``, otherwise the raw distance is returned.
+  :bdg-ref-success:`physics <config-scattered_ore-template-config-ore-base-parameter-physics>` :doc:`/config/documentation/objects/Boolean` 
 
 - :ref:`In CHANNEL in NoiseSampler <object-noisesampler-template-library-image-channel-parameter-premultiply>`:
 
   :bdg-ref-success:`premultiply <object-noisesampler-template-library-image-channel-parameter-premultiply>` :doc:`/config/documentation/objects/Boolean` - Whether to multiply color channels by the alpha channel or not.
 
-- :ref:`In base in ORE <config-ore-template-config-ore-base-parameter-physics>`:
+- :ref:`In DISTANCE_TRANSFORM in NoiseSampler <object-noisesampler-template-library-image-distance_transform-parameter-invert-threshold>`:
 
-  :bdg-ref-success:`physics <config-ore-template-config-ore-base-parameter-physics>` :doc:`/config/documentation/objects/Boolean` 
+  :bdg-ref-success:`invert-threshold <object-noisesampler-template-library-image-distance_transform-parameter-invert-threshold>` :doc:`/config/documentation/objects/Boolean` 
 
 - :ref:`In DISTANCE_TRANSFORM in NoiseSampler <object-noisesampler-template-library-image-distance_transform-parameter-clamp-to-max-edge>`:
 
   :bdg-ref-success:`clamp-to-max-edge <object-noisesampler-template-library-image-distance_transform-parameter-clamp-to-max-edge>` :doc:`/config/documentation/objects/Boolean` 
 
-- :ref:`In DISTANCE_TRANSFORM in NoiseSampler <object-noisesampler-template-library-image-distance_transform-parameter-invert-threshold>`:
+- :ref:`In base in ORE <config-ore-template-config-ore-base-parameter-physics>`:
 
-  :bdg-ref-success:`invert-threshold <object-noisesampler-template-library-image-distance_transform-parameter-invert-threshold>` :doc:`/config/documentation/objects/Boolean` 
+  :bdg-ref-success:`physics <config-ore-template-config-ore-base-parameter-physics>` :doc:`/config/documentation/objects/Boolean` 
 
-- :ref:`In CHANNEL in NoiseSampler <object-noisesampler-template-library-image-channel-parameter-normalize>`:
+- :ref:`In GABOR in NoiseSampler <object-noisesampler-template-config-noise-function-gabor-parameter-isotropic>`:
 
-  :bdg-ref-success:`normalize <object-noisesampler-template-library-image-channel-parameter-normalize>` :doc:`/config/documentation/objects/Boolean` - If the channel should be normalized to range [-1, 1] or not.
+  :bdg-ref-success:`isotropic <object-noisesampler-template-config-noise-function-gabor-parameter-isotropic>` :doc:`/config/documentation/objects/Boolean` 
 
 - :ref:`In BITMAP in Image <object-image-template-library-image-bitmap-parameter-zero-indexed>`:
 
   :bdg-ref-success:`zero-indexed <object-image-template-library-image-bitmap-parameter-zero-indexed>` :doc:`/config/documentation/objects/Boolean` 
 
+- :ref:`In DISTANCE in NoiseSampler <object-noisesampler-template-config-noise-function-distance-parameter-normalize>`:
+
+  :bdg-ref-success:`normalize <object-noisesampler-template-config-noise-function-distance-parameter-normalize>` :doc:`/config/documentation/objects/Boolean` - If set to true, the returned distance will be normalized to be within the range ``[-1, 1]``, otherwise the raw distance is returned.
+
 - :ref:`In ADJACENT_PATTERN in Locator <object-locator-template-config-locators-adjacent_pattern-parameter-match-all>`:
 
   :bdg-ref-success:`match-all <object-locator-template-config-locators-adjacent_pattern-parameter-match-all>` :doc:`/config/documentation/objects/Boolean` 

_sources/config/documentation/objects/ColorSampler.rst.txt

@@ -105,26 +105,26 @@ Uses
 
 Used by 6 parameters:
 
-- :ref:`In SINGLE_IMAGE in ColorSampler <object-colorsampler-template-library-image-single_image-parameter-outside-sampler>`:
-
-  :bdg-ref-primary:`outside-sampler <object-colorsampler-template-library-image-single_image-parameter-outside-sampler>` :doc:`/config/documentation/objects/ColorSampler` - The sampler that provides colors for coordinates outside the bounds of the ``Image`` .
-
-- :ref:`In IMAGE in Source <object-source-template-pipeline-image-image-parameter-color-sampler>`:
+- :ref:`In CHANNEL in NoiseSampler <object-noisesampler-template-library-image-channel-parameter-color-sampler>`:
 
-  :bdg-ref-primary:`color-sampler <object-source-template-pipeline-image-image-parameter-color-sampler>` :doc:`/config/documentation/objects/ColorSampler` 
+  :bdg-ref-primary:`color-sampler <object-noisesampler-template-library-image-channel-parameter-color-sampler>` :doc:`/config/documentation/objects/ColorSampler` - The color sampler to extract channel values from.
 
-- :ref:`In ROTATE in ColorSampler <object-colorsampler-template-library-image-rotate-parameter-color-sampler>`:
+- :ref:`In IMAGE in BiomeProvider <object-biomeprovider-template-biome-provider-image-v2-image-parameter-color-sampler>`:
 
-  :bdg-ref-primary:`color-sampler <object-colorsampler-template-library-image-rotate-parameter-color-sampler>` :doc:`/config/documentation/objects/ColorSampler` 
+  :bdg-ref-primary:`color-sampler <object-biomeprovider-template-biome-provider-image-v2-image-parameter-color-sampler>` :doc:`/config/documentation/objects/ColorSampler` 
 
 - :ref:`In TRANSLATE in ColorSampler <object-colorsampler-template-library-image-translate-parameter-color-sampler>`:
 
   :bdg-ref-primary:`color-sampler <object-colorsampler-template-library-image-translate-parameter-color-sampler>` :doc:`/config/documentation/objects/ColorSampler` 
 
-- :ref:`In IMAGE in BiomeProvider <object-biomeprovider-template-biome-provider-image-v2-image-parameter-color-sampler>`:
+- :ref:`In IMAGE in Source <object-source-template-pipeline-image-image-parameter-color-sampler>`:
 
-  :bdg-ref-primary:`color-sampler <object-biomeprovider-template-biome-provider-image-v2-image-parameter-color-sampler>` :doc:`/config/documentation/objects/ColorSampler` 
+  :bdg-ref-primary:`color-sampler <object-source-template-pipeline-image-image-parameter-color-sampler>` :doc:`/config/documentation/objects/ColorSampler` 
 
-- :ref:`In CHANNEL in NoiseSampler <object-noisesampler-template-library-image-channel-parameter-color-sampler>`:
+- :ref:`In SINGLE_IMAGE in ColorSampler <object-colorsampler-template-library-image-single_image-parameter-outside-sampler>`:
+
+  :bdg-ref-primary:`outside-sampler <object-colorsampler-template-library-image-single_image-parameter-outside-sampler>` :doc:`/config/documentation/objects/ColorSampler` - The sampler that provides colors for coordinates outside the bounds of the ``Image`` .
+
+- :ref:`In ROTATE in ColorSampler <object-colorsampler-template-library-image-rotate-parameter-color-sampler>`:
 
-  :bdg-ref-primary:`color-sampler <object-noisesampler-template-library-image-channel-parameter-color-sampler>` :doc:`/config/documentation/objects/ColorSampler` - The color sampler to extract channel values from.
+  :bdg-ref-primary:`color-sampler <object-colorsampler-template-library-image-rotate-parameter-color-sampler>` :doc:`/config/documentation/objects/ColorSampler`