Skip to content
Permalink
Browse files
expand ansible-doc coverage (#74963)
* Expand ansible-doc to tests/filters and fix existing issues

  enable filter/test docs if in single file or companion yaml
  add docs for several filters/tests plugins
  allow .yml companion for docs for other plugins, must be colocated
  verify plugins are valid (not modules, cannot)
  fix 'per collection' filtering
  limit old style deprecation (_ prefix) to builtin/legacy
  start move to pathlib for saner path handling
  moved some funcitons, kept backwards compat shims with deprecation notice

  Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
  Co-authored-by: Felix Fontein <felix@fontein.de>
  Co-authored-by: Sandra McCann <samccann@redhat.com>
  • Loading branch information
bcoca committed Apr 27, 2022
1 parent a65fbfa commit b439e41a915ccec0ccbabecc966919ea406db74e
Showing 36 changed files with 1,074 additions and 194 deletions.
@@ -24,6 +24,9 @@ recursive-include lib/ansible/module_utils/powershell *.psm1
recursive-include lib/ansible/modules/windows *.ps1
recursive-include lib/ansible/galaxy/data *.yml *.j2 README.md ansible.cfg inventory .git_keep
recursive-include lib/ansible/config *.yml
recursive-include lib/ansible/modules *.yml
recursive-include lib/ansible/plugins/test *.yml
recursive-include lib/ansible/plugins/filter *.yml
recursive-include licenses *.txt
recursive-include packaging *
recursive-include test/ansible_test *.py Makefile
@@ -21,7 +21,29 @@ You can add a custom filter plugin by dropping it into a ``filter_plugins`` dire
Using filter plugins
--------------------

For information on using filter plugins, see :ref:`playbooks_filters`.
You can use filters anywhere you can use templating in Ansible: in a play, in variables file, or in 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

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

passing_positional: {{ (x == 32) | ternary('x is 32', 'x is not 32') }}
passing_extra_named_parameters: {{ some_variable | to_yaml(indent=8, width=1337) }}
passing_both: {{ some_variable| ternary('true value', 'false value', none_val='NULL') }}

In the documentation, filters will always have a C(_input) option that corresponds to the expression to the left of c(|). A C(positional:) field in the documentation will show which options are positional and in which order they are required.


Plugin list
-----------

You can use ``ansible-doc -t filter -l`` to see the list of available plugins. Use ``ansible-doc -t filter <plugin name>`` to see specific documents and examples.


.. seealso::

@@ -9,7 +9,6 @@ Test plugins

Test plugins evaluate template expressions and return True or False. With test plugins you can create :ref:`conditionals <playbooks_conditionals>` to implement the logic of your tasks, blocks, plays, playbooks, and roles. Ansible uses the `standard tests `_ shipped as part of Jinja, and adds some specialized test plugins. You can :ref:`create custom Ansible test plugins <developing_test_plugins>`.

.. _standard tests: https://jinja.palletsprojects.com/en/latest/templates/#builtin-tests

.. _enabling_test:

@@ -24,7 +23,63 @@ You can add a custom test plugin by dropping it into a ``test_plugins`` director
Using test plugins
-------------------

The User Guide offers detailed documentation on :ref:`using test plugins <playbooks_tests>`.
You can use tests anywhere you can use templating in Ansible: in a play, in variables file, or in a Jinja2 template for the :ref:`template <template_module>` module. For more information on using test plugins, see :ref:`playbooks_tests`.

Tests always return ``True`` or ``False``, they are always a boolean, if you need a different return type, you should be looking at filters.

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

vars:
is_ready: '{{ task_result is success }}'

tasks:
- name: conditionals are always in 'template' context
action: dostuff
when: task_result is failed

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

tasks:
- name: pass positional parameter to match test
action: dostuff
when: myurl is match("https://example.com/users/.*/resources")
- name: pass named parameter to truthy test
action: dostuff
when: myvariable is truthy(convert_bool=True)

- name: pass both types to 'version' test
action: dostuff
when: sample_semver_var is version('2.0.0-rc.1+build.123', 'lt', version_type='semver')


Using test plugins with lists
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

As mentioned above, one way to use tests is with the ``select`` familiy of filters (``select``, ``reject``, ``selectattr``, ``rejectattr``).

.. code-block:: YAML+Jinja

# give me only defined variables from a list of variables, using 'defined' test
good_vars: "{{ all_vars|select('defined') }}"

# this uses the 'equalto' test to filter out non 'fixed' type of addresses from a list
only_fixed_addresses: "{{ all_addresses|selectattr('type', 'equalsto', 'fixed') }}"

# this does the opposite of the previous one
only_fixed_addresses: "{{ all_addresses|rejectattr('type', 'equalsto', 'fixed') }}"


Plugin list
-----------

You can use ``ansible-doc -t filter -l`` to see the list of available plugins. Use ``ansible-doc -t filter <plugin name>`` to see specific documents and examples.



.. seealso::

@@ -36,8 +91,8 @@ The User Guide offers detailed documentation on :ref:`using test plugins <playbo
Using conditional statements
:ref:`filter_plugins`
Filter plugins
:ref:`playbooks_filters`
Using filters
:ref:`playbooks_tests`
Using tests
:ref:`lookup_plugins`
Lookup plugins
`User Mailing List <https://groups.google.com/group/ansible-devel>`_

0 comments on commit b439e41

Please sign in to comment.