playbooks_filters: Mention the usage of the ansible.builtin.split fil…

…ter (#1929)

* playbooks_filters: Mention the usage of the ansible.builtin.split filter

This is a filter I frequently used in my project, it should mentioned in the documentation so that it can be easily recognized by users.

Fixes #1928.

* Update docs/docsite/rst/playbook_guide/playbooks_filters.rst

Fix inconsistent heading markup style.

Co-authored-by: Felix Fontein <[email protected]>

* playbooks_filters: Fix incorrect _dict_filter label location

Signed-off-by: 林博仁(Buo-ren Lin) <[email protected]>

* playbooks_filters: Fix incorrect argument of the split builtin filter

Signed-off-by: 林博仁(Buo-ren Lin) <[email protected]>

* playbooks_filters: Fix incorrect example input and output

Signed-off-by: 林博仁(Buo-ren Lin) <[email protected]>

* Update docs/docsite/rst/playbook_guide/playbooks_filters.rst

Increase verbosity.

Co-authored-by: Felix Fontein <[email protected]>

---------

Signed-off-by: 林博仁(Buo-ren Lin) <[email protected]>
Co-authored-by: Felix Fontein <[email protected]>

docs/docsite/rst/playbook_guide/playbooks_filters.rst

@@ -116,6 +116,29 @@ If you are unsure of the underlying Python type of a variable, you can use the :
 
 You should note that, while this may seem like a useful filter for checking that you have the right type of data in a variable, you should often prefer :ref:`type tests <type_tests>`, which will allow you to test for specific data types.
 
+Transforming strings into lists
+-------------------------------
+
+Use the :ansplugin:`ansible.builtin.split#filter` filter to transform a character/string delimited string into a list of items suitable for :ref:`looping <playbooks_loops>`. For example, if you want to split a string variable `fruits` by commas, you can use:
+
+.. code-block:: yaml+jinja
+
+    {{ fruits | split(',') }}
+
+String data (before applying the :ansplugin:`ansible.builtin.split#filter` filter):
+
+.. code-block:: yaml
+
+    fruits: apple,banana,orange
+
+List data (after applying the :ansplugin:`ansible.builtin.split#filter` filter):
+
+.. code-block:: yaml
+
+    - apple
+    - banana
+    - orange
+
 .. _dict_filter:
 
 Transforming dictionaries into lists