Code block languages: normalize casing of yaml and yaml+jinja, update list in style guide, add comments to keep lists in sync (#2848) (#2862)

* Update lists of allowed languages.

* Stick to one casing of yaml and yaml+jinja.

* Add comment to keep lists in sync.

(cherry picked from commit 180ef73)

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

Author: patchback[bot]

docs/docsite/rst/dev_guide/developing_plugins.rst

@@ -439,7 +439,7 @@ Here's a simple lookup plugin implementation --- this lookup returns the content
 
 The following is an example of how this lookup is called:
 
-.. code-block:: YAML
+.. code-block:: yaml
 
   ---
   - hosts: all

docs/docsite/rst/dev_guide/sidecar.rst

@@ -52,7 +52,7 @@ Here is a longer example that shows documentation as embedded in a Python file:
 
 This example shows the same documentation in YAML format:
 
-.. code-block:: YAML
+.. code-block:: yaml
 
   DOCUMENTATION:
     description: something

docs/docsite/rst/dev_guide/style_guide/index.rst

@@ -148,8 +148,11 @@ The Ansible documentation allows the following values:
 * bash
 * console
 * csharp
+* diff
 * ini
+* jinja
 * json
+* md
 * powershell
 * python
 * rst
@@ -160,6 +163,9 @@ The Ansible documentation allows the following values:
 * yaml
 * yaml+jinja
 
+..
+  The above list is enforced by tests/checkers/rst-yamllint.py.
+
 For example, you can highlight Python code using following syntax:
 
 .. code-block:: rst

docs/docsite/rst/module_plugin_guide/plugin_filtering_config.rst

@@ -5,7 +5,7 @@ Rejecting modules
 
 If you want to avoid using certain modules, you can add them to a reject list to prevent Ansible from loading them. To reject plugins, create a yaml configuration file. The default location for this file is :file:`/etc/ansible/plugin_filters.yml`. You can select a different path for the reject list using the :ref:`PLUGIN_FILTERS_CFG` setting in the ``defaults`` section of your ``ansible.cfg``. Here is an example reject list:
 
-.. code-block:: YAML
+.. code-block:: yaml
 
     ---
     filter_version: '1.0'

docs/docsite/rst/playbook_guide/complex_data_manipulation.rst

@@ -59,7 +59,7 @@ The Python equivalent code would be:
 
 There are several ways to do it in Ansible, this is just one example:
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
  :emphasize-lines: 4
  :caption: Way to extract matching keys from a list of dictionaries
 
@@ -99,7 +99,7 @@ There are several ways to do it in Ansible, this is just one example:
     }
 
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
  :caption: Get the unique list of values of a variable that vary per host
 
     vars:
@@ -113,7 +113,7 @@ Find mount point
 
 In this case, we want to find the mount point for a given path across our machines, since we already collect mount facts, we can use the following:
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
  :caption: Use selectattr to filter mounts into the list I can then sort and select the last from
  :emphasize-lines: 8
 
@@ -133,7 +133,7 @@ Combine values from same list of dicts
 ---------------------------------------
 Combining positive and negative filters from the examples above, you can get a 'value when it exists' and a 'fallback' when it doesn't.
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
  :caption: Use selectattr and rejectattr to get the ansible_host or inventory_hostname as needed
 
     - hosts: localhost
@@ -155,7 +155,7 @@ Custom Fileglob Based on a Variable
 
 This example uses `Python argument list unpacking <https://docs.python.org/3/tutorial/controlflow.html#unpacking-argument-lists>`_ to create a custom list of fileglobs based on a variable.
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
   :caption: Using fileglob with a list based on a variable.
 
     - hosts: all
@@ -192,15 +192,15 @@ In most languages, it is easy to create a dictionary (also known as map/associat
 
 These example produces ``{"a": "b", "c": "d"}``
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
  :caption: Simple list to dict by assuming the list is [key, value , key, value, ...]
 
   vars:
       single_list: [ 'a', 'b', 'c', 'd' ]
       mydict: "{{ dict(single_list[::2] | zip_longest(single_list[1::2])) }}"
 
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
  :caption: It is simpler when we have a list of pairs:
 
   vars:
@@ -213,7 +213,7 @@ Both end up being the same thing, with ``zip_longest`` transforming ``single_lis
 
 A bit more complex, using ``set_fact`` and a ``loop`` to create/update a dictionary with key value pairs from 2 lists:
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
  :caption: Using set_fact to create a dictionary from a set of lists
  :emphasize-lines: 3, 4
 
@@ -236,7 +236,7 @@ This results in ``{"foo": "a", "var": "b", "bar": "c"}``.
 
 You can even combine these simple examples with other filters and lookups to create a dictionary dynamically by matching patterns to variable names:
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
  :caption: Using 'vars' to define dictionary from a set of lists without needing a task
 
     vars:
@@ -257,14 +257,14 @@ A quick explanation, since there is a lot to unpack from these two lines:
 An example of how to use facts to find a host's data that meets condition X:
 
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
 
   vars:
     uptime_of_host_most_recently_rebooted: "{{ansible_play_hosts_all | map('extract', hostvars, 'ansible_uptime_seconds') | sort | first}}"
 
 An example to show a host uptime in days/hours/minutes/seconds (assuming facts were gathered).
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
 
  - name: Show the uptime in days/hours/minutes/seconds
    ansible.builtin.debug:

docs/docsite/rst/playbook_guide/playbooks_blocks.rst

@@ -14,7 +14,7 @@ Grouping tasks with blocks
 
 All tasks in a block inherit directives applied at the block level. Most of what you can apply to a single task (with the exception of loops) can be applied at the block level, so blocks make it much easier to set data or directives common to the tasks. The directive does not affect the block itself, it is only inherited by the tasks enclosed by a block. For example, a `when` statement is applied to the tasks within a block, not to the block itself.
 
-.. code-block:: YAML
+.. code-block:: yaml
  :emphasize-lines: 3
  :caption: Block example with named tasks inside the block
 
@@ -65,7 +65,7 @@ You can control how Ansible responds to task errors using blocks with ``rescue``
 Rescue blocks specify tasks to run when an earlier task in a block fails. This approach is similar to exception handling in many programming languages. Ansible only runs rescue blocks after a task returns a 'failed' state.
 
 .. _block_rescue:
-.. code-block:: YAML
+.. code-block:: yaml
  :emphasize-lines: 3,14
  :caption: Block error handling example
 
@@ -90,7 +90,7 @@ Rescue blocks specify tasks to run when an earlier task in a block fails. This a
 You can also add an ``always`` section to a block. Tasks in the ``always`` section run no matter what the task status of the previous block is.
 
 .. _block_always:
-.. code-block:: YAML
+.. code-block:: yaml
  :emphasize-lines: 3,14
  :caption: Block with always section
 
@@ -114,7 +114,7 @@ You can also add an ``always`` section to a block. Tasks in the ``always`` secti
 
 Together, these elements offer complex error handling.
 
-.. code-block:: YAML
+.. code-block:: yaml
  :emphasize-lines: 3,14,25
  :caption: Block with all sections
 
@@ -153,7 +153,7 @@ If an error occurs in the block and the rescue task succeeds, Ansible reverts th
 
 You can use blocks with ``flush_handlers`` in a rescue task to ensure that all handlers run even if an error occurs:
 
-.. code-block:: YAML
+.. code-block:: yaml
  :emphasize-lines: 3,12
  :caption: Block run handlers in error handling
 
@@ -189,7 +189,7 @@ ansible_failed_result
 
 These can be inspected in the ``rescue`` section:
 
-.. code-block:: YAML
+.. code-block:: yaml
  :emphasize-lines: 11,16
  :caption: Use special variables in rescue section.
 

docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst

@@ -7,7 +7,7 @@ If you frequently call the same module with the same arguments, it can be useful
 
 Here is a basic example:
 
-.. code-block:: YAML
+.. code-block:: yaml
 
     - hosts: localhost
       module_defaults:
@@ -33,7 +33,7 @@ Here is a basic example:
 
 The ``module_defaults`` keyword can be used at the play, block, and task level. Any module arguments explicitly specified in a task will override any established default for that module argument.
 
-.. code-block:: YAML
+.. code-block:: yaml
 
     - block:
         - name: Print a message
@@ -45,7 +45,7 @@ The ``module_defaults`` keyword can be used at the play, block, and task level.
 
 You can remove any previously established defaults for a module by specifying an empty dict.
 
-.. code-block:: YAML
+.. code-block:: yaml
 
     - name: Create file1
       ansible.builtin.file:
@@ -61,7 +61,7 @@ Here are some more realistic use cases for this feature.
 
 Interacting with an API that requires auth.
 
-.. code-block:: YAML
+.. code-block:: yaml
 
     - hosts: localhost
       module_defaults:
@@ -84,7 +84,7 @@ Interacting with an API that requires auth.
 
 Setting a default AWS region for specific EC2-related modules.
 
-.. code-block:: YAML
+.. code-block:: yaml
 
     - hosts: localhost
       vars:
@@ -110,7 +110,7 @@ Module default groups allow to provide common parameters to groups of modules th
 Here is an example ``runtime.yml`` file for the ``ns.coll`` collection.
 This file defines an action group named ``ns.coll.my_group`` and places the ``sample_module`` from ``ns.coll`` and ``another_module`` from ``another.collection`` into the group.
 
-.. code-block:: YAML
+.. code-block:: yaml
 
   # collections/ansible_collections/ns/coll/meta/runtime.yml
   action_groups:
@@ -120,7 +120,7 @@ This file defines an action group named ``ns.coll.my_group`` and places the ``sa
 
 This group can now be used in a playbook like this:
 
-.. code-block:: YAML
+.. code-block:: yaml
 
   - hosts: localhost
     module_defaults:
@@ -160,7 +160,7 @@ Use the groups with ``module_defaults`` by prefixing the group name with ``group
 
 In a playbook, you can set module defaults for whole groups of modules, such as setting a common AWS region.
 
-.. code-block:: YAML
+.. code-block:: yaml
 
     # example_play.yml
     - hosts: localhost

docs/docsite/rst/plugins/filter.rst

@@ -23,14 +23,14 @@ Using filter plugins
 
 You can use filters anywhere you can use templating in Ansible: in a play, in variables file, or a Jinja2 template for the :ref:`template <template_module>` module. For more information on using filter plugins, see :ref:`playbooks_filters`.  Filters can return any type of data, but if you want to always return a boolean, (``true`` or ``false``) you should be looking at a test instead.
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
 
   vars:
      yaml_string: "{{ some_variable|to_yaml }}"
 
 Filters are the preferred way to manipulate data in Ansible, you can identify a filter because it is normally preceded by a ``|``, with the expression on the left of it being the first input of the filter. Additional parameters may be passed into the filter itself as you would to most programming functions. These parameters can be either ``positional`` (passed in order) or ``named`` (passed as key=value pairs). When passing both types, positional arguments should go first.
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
 
    passing_positional: "{{ (x == 32) | ternary('x is 32', 'x is not 32') }}"
    passing_extra_named_parameters: "{{ some_variable | to_yaml(indent=8, width=1337) }}"

docs/docsite/rst/plugins/lookup.rst

@@ -34,14 +34,14 @@ Using lookup plugins
 
 You can use lookup plugins anywhere you can use templating in Ansible: in a play, in variables file, or a Jinja2 template for the :ref:`template <template_module>` module. For more information on using lookup plugins, see :ref:`playbooks_lookups`.
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
 
   vars:
     file_contents: "{{ lookup('file', 'path/to/file.txt') }}"
 
 Lookups are an integral part of loops. Wherever you see ``with_``, the part after the underscore is the name of a lookup. For this reason, lookups are expected to output lists; for example, ``with_items`` uses the :ref:`items <items_lookup>` lookup:
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
 
   tasks:
     - name: count to 3
@@ -50,7 +50,7 @@ Lookups are an integral part of loops. Wherever you see ``with_``, the part afte
 
 You can combine lookups with :ref:`filters <playbooks_filters>`, :ref:`tests <playbooks_tests>` and even each other to do some complex data generation and manipulation. For example:
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
 
   tasks:
     - name: Complicated chained lookups and filters
@@ -66,7 +66,7 @@ You can control how errors behave in all lookup plugins by setting ``errors`` to
 
 To ignore lookup errors:
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
 
     - name: if this file does not exist, I do not care .. file plugin itself warns anyway ...
       debug: msg="{{ lookup('file', '/nosuchfile', errors='ignore') }}"
@@ -82,7 +82,7 @@ To ignore lookup errors:
 
 To get a warning instead of a failure:
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
 
     - name: if this file does not exist, let me know, but continue
       debug: msg="{{ lookup('file', '/nosuchfile', errors='warn') }}"
@@ -100,7 +100,7 @@ To get a warning instead of a failure:
 
 To get a fatal error (the default):
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
 
     - name: if this file does not exist, FAIL (this is the default)
       debug: msg="{{ lookup('file', '/nosuchfile', errors='strict') }}"

docs/docsite/rst/plugins/test.rst

@@ -29,7 +29,7 @@ Tests always return ``True`` or ``False``, they are always a boolean, if you nee
 
 You can recognize test plugins by the use of the ``is`` statement in a template, they can also be used as part of the ``select`` family of filters.
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
 
   vars:
     is_ready: '{{ task_result is success }}'
@@ -41,7 +41,7 @@ You can recognize test plugins by the use of the ``is`` statement in a template,
 
 Tests will always have an ``_input`` and this is normally what is on the left side of ``is``. Tests can also take additional parameters as you would to most programming functions. These parameters can be either ``positional`` (passed in order) or ``named`` (passed as key=value pairs). When passing both types, positional arguments should go first.
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
 
   tasks:
   - name: pass a positional parameter to match test
@@ -62,7 +62,7 @@ Using test plugins with lists
 
 As mentioned above, one way to use tests is with the ``select`` family of filters (``select``, ``reject``, ``selectattr``, ``rejectattr``).
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml+jinja
 
    # give me only defined variables from a list of variables, using 'defined' test
    good_vars: "{{ all_vars|select('defined') }}"