From 490e3bef59f9eb6384dbac383212cd032bcd77a1 Mon Sep 17 00:00:00 2001
From: "Jesse Pretorius (odyssey4me)" <jesse@odyssey4.me>
Date: Tue, 14 Jun 2022 15:41:18 +0100
Subject: [PATCH] Add more complete examples with sample output

The existing examples from code are not sufficient to explain
how the various features of the module can be used. This patch
hopes to add more practical examples to show some of the
features.

Hopefully this also sets a trend so that more examples are added
in the future.

Change-Id: I035ce06a2391904724aaf8b0a724d7b4fa8e27f0
---
 doc/source/index.rst | 141 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 133 insertions(+), 8 deletions(-)

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 0c2ada7..1e2e312 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -15,6 +15,139 @@ Renders template files providing a create/update override interface
 - The module is an extension of the **copy** module and all of attributes that
   can be set there are available to be set here.
 
+Examples
+--------
+
+Example for .conf
+^^^^^^^^^^^^^^^^^
+The `config_template` plugin has a variety of tools available. A .conf file
+may include options that are not normally supported in an INI file, but are
+used in OpenStack, like ListOpt and MultiStrOpt.
+
+Even though we are generating a .conf file, we specify the `config_type`` of
+`ini`` when using config_template.
+
+Playbook:
+
+.. code-block :: yaml
+
+  - hosts: localhost
+    connection: local
+    gather_facts: no
+    tasks:
+      - config_template:
+          content: |
+            [foo]
+            bar = baz
+
+            [section1]
+            option1 = value1
+          dest: "test_dst.conf"
+          config_type: "ini"
+          config_overrides:
+            hello:
+              cruel: world
+            section1:
+              option1: value2
+            orderedListSection:
+              listOpt:
+                - listItem1
+                - listItem2
+            multiStrOpSection:
+              multiStrOpOption:
+                ? multiStrOp1
+                ? multiStrOp2
+
+Resulting file on the remote host:
+
+.. code-block :: ini
+
+  [foo]
+  bar = baz
+
+  [section1]
+  option1 = value2
+
+  [hello]
+  cruel = world
+
+  [orderedListSection]
+  listOpt = listItem1,listItem2
+
+  [multiStrOpSection]
+  multiStrOpOption = multiStrOp1
+  multiStrOpOption = multiStrOp2
+
+A practical example would be for something like OpenStack's nova.conf where the input of:
+
+.. code-block :: yaml
+
+nova_conf_override:
+  filter_scheduler:
+    enabled_filters:
+      - ComputeFilter
+      - ServerGroupAntiAffinityFilter
+      - ServerGroupAffinityFilter
+      - NUMATopologyFilter
+  pci:
+    ? passthrough_whitelist: '{"address":"*:0a:00.*", "physical_network":"physnet1"}'
+    ? passthrough_whitelist: '{"address": {"domain": ".*", "bus": "02", "slot": "01", "function": "[0-2]"}, "physical_network":"net1"}'
+    ? passthrough_whitelist: '{"vendor_id":"1137","product_id":"0071"}'
+
+Would produce:
+
+.. code-block :: ini
+
+  [filter_scheduler]
+  enabled_filters = ComputeFilter,ServerGroupAntiAffinityFilter,ServerGroupAffinityFilter,NUMATopologyFilter
+
+  [pci]
+  passthrough_whitelist = '{"address":"*:0a:00.*", "physical_network":"physnet1"}'
+  passthrough_whitelist = '{"address": {"domain": ".*", "bus": "02", "slot": "01", "function": "[0-2]"}, "physical_network":"net1"}'
+  passthrough_whitelist = '{"vendor_id":"1137","product_id":"0071"}'
+
+Example for .ini with remote_src
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The `remote_src: true` argument instructs `config_template` to use a file that
+is already on the remote host as the source content.
+
+Input file on the remote host:
+
+.. code-block :: ini
+
+  [foo]
+  # comment
+  bar = baz
+
+  [hello]
+
+Playbook:
+
+.. code-block :: yaml
+
+  - hosts: remote_host
+    gather_facts: no
+    tasks:
+      - config_template:
+          remote_src: true
+          src: "/etc/test_src.ini"
+          dest: "/etc/test_dst.ini"
+          config_type: "ini"
+          config_overrides:
+            hello:
+              cruel: world
+
+Resulting file on the remote host:
+
+.. code-block :: ini
+
+  [foo]
+  # comment
+  bar = baz
+
+  [hello]
+  cruel = world
+
 Loading
 -------
 
@@ -38,11 +171,3 @@ you in a given project. To do this add the following lines to your
 
 .. literalinclude:: ../../examples/ansible-role-requirements.yml
    :language: yaml
-
-Examples
---------
-
-.. literalinclude:: ../../library/config_template
-   :language: yaml
-   :start-after: EXAMPLES = """
-   :end-before: """