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

@@ -15,6 +15,137 @@ 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:
+      - openstack.config_template.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
+        - NUMATopologyFilter
+    pci:
+      ? passthrough_whitelist: '{"address":"*:0a:00.*",
+        "physical_network":"pn1"}'
+      ? passthrough_whitelist: '{"vendor_id":"1137","product_id":"0071"}'
+
+Would produce:
+
+.. code-block :: ini
+
+  [filter_scheduler]
+  enabled_filters = ComputeFilter,NUMATopologyFilter
+
+  [pci]
+  passthrough_whitelist = '{"address":"*:0a:00.*", "physical_network":"pn1"}'
+  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 +169,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: """