From 57053f8a3286d9ae1551c5cc061390b648482c4b Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 30 Oct 2023 23:19:01 +0100 Subject: [PATCH] [PR #7444/2a7f9f28 backport][stable-7] Improve docsite extra docs (#7453) Improve docsite extra docs (#7444) * Improve markup. * Improve filter and test guides by linking to plugins and using FQCNs more consistently. * list_merge is an option, not the filter's name. * Improve filter docs. (cherry picked from commit 2a7f9f28b9f5f846cc0b763b03314dd6c9a00057) Co-authored-by: Felix Fontein --- ...rmations_counting_elements_in_sequence.rst | 2 +- ...ide_abstract_informations_dictionaries.rst | 4 ++-- ...r_guide_abstract_informations_grouping.rst | 2 +- ...rmations_merging_lists_of_dictionaries.rst | 22 +++++++++---------- docs/docsite/rst/filter_guide_conversions.rst | 6 ++--- .../rst/filter_guide_creating_identifiers.rst | 4 ++-- docs/docsite/rst/filter_guide_paths.rst | 12 +--------- .../rst/filter_guide_selecting_json_data.rst | 4 ++-- .../rst/filter_guide_working_with_times.rst | 22 +++++++++---------- .../rst/filter_guide_working_with_unicode.rst | 6 ++--- .../filter_guide_working_with_versions.rst | 2 +- docs/docsite/rst/test_guide.rst | 2 +- 12 files changed, 39 insertions(+), 49 deletions(-) diff --git a/docs/docsite/rst/filter_guide_abstract_informations_counting_elements_in_sequence.rst b/docs/docsite/rst/filter_guide_abstract_informations_counting_elements_in_sequence.rst index dcadd5a793..98e8eb1c4d 100644 --- a/docs/docsite/rst/filter_guide_abstract_informations_counting_elements_in_sequence.rst +++ b/docs/docsite/rst/filter_guide_abstract_informations_counting_elements_in_sequence.rst @@ -6,7 +6,7 @@ Counting elements in a sequence ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The ``community.general.counter`` filter plugin allows you to count (hashable) elements in a sequence. Elements are returned as dictionary keys and their counts are stored as dictionary values. +The :ansplugin:`community.general.counter filter plugin ` allows you to count (hashable) elements in a sequence. Elements are returned as dictionary keys and their counts are stored as dictionary values. .. code-block:: yaml+jinja diff --git a/docs/docsite/rst/filter_guide_abstract_informations_dictionaries.rst b/docs/docsite/rst/filter_guide_abstract_informations_dictionaries.rst index 840bd1542c..3059b00321 100644 --- a/docs/docsite/rst/filter_guide_abstract_informations_dictionaries.rst +++ b/docs/docsite/rst/filter_guide_abstract_informations_dictionaries.rst @@ -6,7 +6,7 @@ Dictionaries ^^^^^^^^^^^^ -You can use the ``dict_kv`` filter to create a single-entry dictionary with ``value | community.general.dict_kv(key)``: +You can use the :ansplugin:`community.general.dict_kv filter ` to create a single-entry dictionary with ``value | community.general.dict_kv(key)``: .. code-block:: yaml+jinja @@ -58,7 +58,7 @@ This produces: .. versionadded:: 2.0.0 -If you need to convert a list of key-value pairs to a dictionary, you can use the ``dict`` function. Unfortunately, this function cannot be used with ``map``. For this, the ``community.general.dict`` filter can be used: +If you need to convert a list of key-value pairs to a dictionary, you can use the ``dict`` function. Unfortunately, this function cannot be used with ``map``. For this, the :ansplugin:`community.general.dict filter ` can be used: .. code-block:: yaml+jinja diff --git a/docs/docsite/rst/filter_guide_abstract_informations_grouping.rst b/docs/docsite/rst/filter_guide_abstract_informations_grouping.rst index 2cea7f9bab..cb15989659 100644 --- a/docs/docsite/rst/filter_guide_abstract_informations_grouping.rst +++ b/docs/docsite/rst/filter_guide_abstract_informations_grouping.rst @@ -6,7 +6,7 @@ Grouping ^^^^^^^^ -If you have a list of dictionaries, the Jinja2 ``groupby`` filter allows to group the list by an attribute. This results in a list of ``(grouper, list)`` namedtuples, where ``list`` contains all dictionaries where the selected attribute equals ``grouper``. If you know that for every ``grouper``, there will be a most one entry in that list, you can use the ``community.general.groupby_as_dict`` filter to convert the original list into a dictionary which maps ``grouper`` to the corresponding dictionary. +If you have a list of dictionaries, the Jinja2 ``groupby`` filter allows to group the list by an attribute. This results in a list of ``(grouper, list)`` namedtuples, where ``list`` contains all dictionaries where the selected attribute equals ``grouper``. If you know that for every ``grouper``, there will be a most one entry in that list, you can use the :ansplugin:`community.general.groupby_as_dict filter ` to convert the original list into a dictionary which maps ``grouper`` to the corresponding dictionary. One example is ``ansible_facts.mounts``, which is a list of dictionaries where each has one ``device`` element to indicate the device which is mounted. Therefore, ``ansible_facts.mounts | community.general.groupby_as_dict('device')`` is a dictionary mapping a device to the mount information: diff --git a/docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst b/docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst index 9b56e98d7e..06fa79d16a 100644 --- a/docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst +++ b/docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst @@ -6,7 +6,7 @@ Merging lists of dictionaries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you have two or more lists of dictionaries and want to combine them into a list of merged dictionaries, where the dictionaries are merged by an attribute, you can use the ``lists_mergeby`` filter. +If you have two or more lists of dictionaries and want to combine them into a list of merged dictionaries, where the dictionaries are merged by an attribute, you can use the :ansplugin:`community.general.lists_mergeby filter `. .. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ref:`the documentation for the community.general.yaml callback plugin `. @@ -76,15 +76,15 @@ This produces the same result as in the previous example: name: meh -The filter also accepts two optional parameters: ``recursive`` and ``list_merge``. These parameters are only supported when used with ansible-base 2.10 or ansible-core, but not with Ansible 2.9. This is available since community.general 4.4.0. +The filter also accepts two optional parameters: :ansopt:`community.general.lists_mergeby#filter:recursive` and :ansopt:`community.general.lists_mergeby#filter:list_merge`. This is available since community.general 4.4.0. **recursive** - Is a boolean, default to ``False``. Should the ``community.general.lists_mergeby`` recursively merge nested hashes. Note: It does not depend on the value of the ``hash_behaviour`` setting in ``ansible.cfg``. + Is a boolean, default to ``false``. Should the :ansplugin:`community.general.lists_mergeby#filter` filter recursively merge nested hashes. Note: It does not depend on the value of the ``hash_behaviour`` setting in ``ansible.cfg``. **list_merge** - Is a string, its possible values are ``replace`` (default), ``keep``, ``append``, ``prepend``, ``append_rp`` or ``prepend_rp``. It modifies the behaviour of ``community.general.lists_mergeby`` when the hashes to merge contain arrays/lists. + Is a string, its possible values are :ansval:`replace` (default), :ansval:`keep`, :ansval:`append`, :ansval:`prepend`, :ansval:`append_rp` or :ansval:`prepend_rp`. It modifies the behaviour of :ansplugin:`community.general.lists_mergeby#filter` when the hashes to merge contain arrays/lists. -The examples below set ``recursive=true`` and display the differences among all six options of ``list_merge``. Functionality of the parameters is exactly the same as in the filter ``combine``. See :ref:`Combining hashes/dictionaries ` to learn details about these options. +The examples below set :ansopt:`community.general.lists_mergeby#filter:recursive=true` and display the differences among all six options of :ansopt:`community.general.lists_mergeby#filter:list_merge`. Functionality of the parameters is exactly the same as in the filter :ansplugin:`ansible.builtin.combine#filter`. See :ref:`Combining hashes/dictionaries ` to learn details about these options. Let us use the lists below in the following examples @@ -110,7 +110,7 @@ Let us use the lists below in the following examples - name: myname02 param01: [3, 4, 4, {key: value}] -Example ``list_merge=replace`` (default): +Example :ansopt:`community.general.lists_mergeby#filter:list_merge=replace` (default): .. code-block:: yaml+jinja @@ -137,7 +137,7 @@ This produces: - 4 - key: value -Example ``list_merge=keep``: +Example :ansopt:`community.general.lists_mergeby#filter:list_merge=keep`: .. code-block:: yaml+jinja @@ -165,7 +165,7 @@ This produces: - 2 - 3 -Example ``list_merge=append``: +Example :ansopt:`community.general.lists_mergeby#filter:list_merge=append`: .. code-block:: yaml+jinja @@ -198,7 +198,7 @@ This produces: - 4 - key: value -Example ``list_merge=prepend``: +Example :ansopt:`community.general.lists_mergeby#filter:list_merge=prepend`: .. code-block:: yaml+jinja @@ -231,7 +231,7 @@ This produces: - 2 - 3 -Example ``list_merge=append_rp``: +Example :ansopt:`community.general.lists_mergeby#filter:list_merge=append_rp`: .. code-block:: yaml+jinja @@ -263,7 +263,7 @@ This produces: - 4 - key: value -Example ``list_merge=prepend_rp``: +Example :ansopt:`community.general.lists_mergeby#filter:list_merge=prepend_rp`: .. code-block:: yaml+jinja diff --git a/docs/docsite/rst/filter_guide_conversions.rst b/docs/docsite/rst/filter_guide_conversions.rst index 78970c17b9..ca0401762c 100644 --- a/docs/docsite/rst/filter_guide_conversions.rst +++ b/docs/docsite/rst/filter_guide_conversions.rst @@ -9,7 +9,7 @@ Conversions Parsing CSV files ^^^^^^^^^^^^^^^^^ -Ansible offers the :ref:`community.general.read_csv module ` to read CSV files. Sometimes you need to convert strings to CSV files instead. For this, the ``from_csv`` filter exists. +Ansible offers the :ansplugin:`community.general.read_csv module ` to read CSV files. Sometimes you need to convert strings to CSV files instead. For this, the :ansplugin:`community.general.from_csv filter ` exists. .. code-block:: yaml+jinja @@ -42,7 +42,7 @@ This produces: ] } -The ``from_csv`` filter has several keyword arguments to control its behavior: +The :ansplugin:`community.general.from_csv filter ` has several keyword arguments to control its behavior: :dialect: Dialect of the CSV file. Default is ``excel``. Other possible choices are ``excel-tab`` and ``unix``. If one of ``delimiter``, ``skipinitialspace`` or ``strict`` is specified, ``dialect`` is ignored. :fieldnames: A set of column names to use. If not provided, the first line of the CSV is assumed to contain the column names. @@ -55,7 +55,7 @@ The ``from_csv`` filter has several keyword arguments to control its behavior: Converting to JSON ^^^^^^^^^^^^^^^^^^ -`JC `_ is a CLI tool and Python library which allows to interpret output of various CLI programs as JSON. It is also available as a filter in community.general. This filter needs the `jc Python library `_ installed on the controller. +`JC `_ is a CLI tool and Python library which allows to interpret output of various CLI programs as JSON. It is also available as a filter in community.general, called :ansplugin:`community.general.jc#filter`. This filter needs the `jc Python library `_ installed on the controller. .. code-block:: yaml+jinja diff --git a/docs/docsite/rst/filter_guide_creating_identifiers.rst b/docs/docsite/rst/filter_guide_creating_identifiers.rst index af0a8b7bab..6e0c730c60 100644 --- a/docs/docsite/rst/filter_guide_creating_identifiers.rst +++ b/docs/docsite/rst/filter_guide_creating_identifiers.rst @@ -11,7 +11,7 @@ The following filters allow to create identifiers. Hashids ^^^^^^^ -`Hashids `_ allow to convert sequences of integers to short unique string identifiers. This filter needs the `hashids Python library `_ installed on the controller. +`Hashids `_ allow to convert sequences of integers to short unique string identifiers. The :ansplugin:`community.general.hashids_encode#filter` and :ansplugin:`community.general.hashids_decode#filter` filters need the `hashids Python library `_ installed on the controller. .. code-block:: yaml+jinja @@ -52,7 +52,7 @@ The hashids filters accept keyword arguments to allow fine-tuning the hashids ge Random MACs ^^^^^^^^^^^ -You can use the ``random_mac`` filter to complete a partial `MAC address `_ to a random 6-byte MAC address. +You can use the :ansplugin:`community.general.random_mac filter ` to complete a partial `MAC address `_ to a random 6-byte MAC address. .. code-block:: yaml+jinja diff --git a/docs/docsite/rst/filter_guide_paths.rst b/docs/docsite/rst/filter_guide_paths.rst index dac8931454..41185832f2 100644 --- a/docs/docsite/rst/filter_guide_paths.rst +++ b/docs/docsite/rst/filter_guide_paths.rst @@ -6,14 +6,4 @@ Paths ----- -The ``path_join`` filter has been added in ansible-base 2.10. If you want to use this filter, but also need to support Ansible 2.9, you can use ``community.general``'s ``path_join`` shim, ``community.general.path_join``. This filter redirects to ``path_join`` for ansible-base 2.10 and ansible-core 2.11 or newer, and re-implements the filter for Ansible 2.9. - -.. code-block:: yaml+jinja - - # ansible-base 2.10 or newer: - path: {{ ('/etc', path, 'subdir', file) | path_join }} - - # Also works with Ansible 2.9: - path: {{ ('/etc', path, 'subdir', file) | community.general.path_join }} - -.. versionadded:: 3.0.0 +The :ansplugin:`ansible.builtin.path_join filter ` has been added in ansible-base 2.10. Community.general 3.0.0 and newer contains an alias ``community.general.path_join`` for this filter that could be used on Ansible 2.9 as well. Since community.general no longer supports Ansible 2.9, this is now a simple redirect to :ansplugin:`ansible.builtin.path_join filter `. diff --git a/docs/docsite/rst/filter_guide_selecting_json_data.rst b/docs/docsite/rst/filter_guide_selecting_json_data.rst index d8de07b926..73dbf985ba 100644 --- a/docs/docsite/rst/filter_guide_selecting_json_data.rst +++ b/docs/docsite/rst/filter_guide_selecting_json_data.rst @@ -8,7 +8,7 @@ Selecting JSON data: JSON queries --------------------------------- -To select a single element or a data subset from a complex data structure in JSON format (for example, Ansible facts), use the ``json_query`` filter. The ``json_query`` filter lets you query a complex JSON structure and iterate over it using a loop structure. +To select a single element or a data subset from a complex data structure in JSON format (for example, Ansible facts), use the :ansplugin:`community.general.json_query filter `. The :ansplugin:`community.general.json_query#filter` filter lets you query a complex JSON structure and iterate over it using a loop structure. .. note:: You must manually install the **jmespath** dependency on the Ansible controller before using this filter. This filter is built upon **jmespath**, and you can use the same syntax. For examples, see `jmespath examples `_. @@ -146,4 +146,4 @@ To extract ports from all clusters with name containing 'server1': vars: server_name_query: "domain.server[?contains(name,'server1')].port" -.. note:: while using ``starts_with`` and ``contains``, you have to use `` to_json | from_json `` filter for correct parsing of data structure. +.. note:: while using ``starts_with`` and ``contains``, you have to use ``to_json | from_json`` filter for correct parsing of data structure. diff --git a/docs/docsite/rst/filter_guide_working_with_times.rst b/docs/docsite/rst/filter_guide_working_with_times.rst index dc68f2a2e3..032d44bb57 100644 --- a/docs/docsite/rst/filter_guide_working_with_times.rst +++ b/docs/docsite/rst/filter_guide_working_with_times.rst @@ -6,9 +6,9 @@ Working with times ------------------ -The ``to_time_unit`` filter allows to convert times from a human-readable string to a unit. For example, ``'4h 30min 12second' | community.general.to_time_unit('hour')`` gives the number of hours that correspond to 4 hours, 30 minutes and 12 seconds. +The :ansplugin:`community.general.to_time_unit filter ` allows to convert times from a human-readable string to a unit. For example, ``'4h 30min 12second' | community.general.to_time_unit('hour')`` gives the number of hours that correspond to 4 hours, 30 minutes and 12 seconds. -There are shorthands to directly convert to various units, like ``to_hours``, ``to_minutes``, ``to_seconds``, and so on. The following table lists all units that can be used: +There are shorthands to directly convert to various units, like :ansplugin:`community.general.to_hours#filter`, :ansplugin:`community.general.to_minutes#filter`, :ansplugin:`community.general.to_seconds#filter`, and so on. The following table lists all units that can be used: .. list-table:: Units :widths: 25 25 25 25 @@ -21,37 +21,37 @@ There are shorthands to directly convert to various units, like ``to_hours``, `` * - Millisecond - 1/1000 second - ``ms``, ``millisecond``, ``milliseconds``, ``msec``, ``msecs``, ``msecond``, ``mseconds`` - - ``to_milliseconds`` + - :ansplugin:`community.general.to_milliseconds#filter` * - Second - 1 second - ``s``, ``sec``, ``secs``, ``second``, ``seconds`` - - ``to_seconds`` + - :ansplugin:`community.general.to_seconds#filter` * - Minute - 60 seconds - ``m``, ``min``, ``mins``, ``minute``, ``minutes`` - - ``to_minutes`` + - :ansplugin:`community.general.to_minutes#filter` * - Hour - 60*60 seconds - ``h``, ``hour``, ``hours`` - - ``to_hours`` + - :ansplugin:`community.general.to_hours#filter` * - Day - 24*60*60 seconds - ``d``, ``day``, ``days`` - - ``to_days`` + - :ansplugin:`community.general.to_days#filter` * - Week - 7*24*60*60 seconds - ``w``, ``week``, ``weeks`` - - ``to_weeks`` + - :ansplugin:`community.general.to_weeks#filter` * - Month - 30*24*60*60 seconds - ``mo``, ``month``, ``months`` - - ``to_months`` + - :ansplugin:`community.general.to_months#filter` * - Year - 365*24*60*60 seconds - ``y``, ``year``, ``years`` - - ``to_years`` + - :ansplugin:`community.general.to_years#filter` -Note that months and years are using a simplified representation: a month is 30 days, and a year is 365 days. If you need different definitions of months or years, you can pass them as keyword arguments. For example, if you want a year to be 365.25 days, and a month to be 30.5 days, you can write ``'11months 4' | community.general.to_years(year=365.25, month=30.5)``. These keyword arguments can be specified to ``to_time_unit`` and to all shorthand filters. +Note that months and years are using a simplified representation: a month is 30 days, and a year is 365 days. If you need different definitions of months or years, you can pass them as keyword arguments. For example, if you want a year to be 365.25 days, and a month to be 30.5 days, you can write ``'11months 4' | community.general.to_years(year=365.25, month=30.5)``. These keyword arguments can be specified to :ansplugin:`community.general.to_time_unit#filter` and to all shorthand filters. .. code-block:: yaml+jinja diff --git a/docs/docsite/rst/filter_guide_working_with_unicode.rst b/docs/docsite/rst/filter_guide_working_with_unicode.rst index 2e5a67f8fa..e75b0f871b 100644 --- a/docs/docsite/rst/filter_guide_working_with_unicode.rst +++ b/docs/docsite/rst/filter_guide_working_with_unicode.rst @@ -6,9 +6,9 @@ Working with Unicode --------------------- -`Unicode `_ makes it possible to produce two strings which may be visually equivalent, but are comprised of distinctly different characters/character sequences. To address this ``Unicode`` defines `normalization forms `_ which avoid these distinctions by choosing a unique character sequence for a given visual representation. +`Unicode `_ makes it possible to produce two strings which may be visually equivalent, but are comprised of distinctly different characters/character sequences. To address this Unicode defines `normalization forms `_ which avoid these distinctions by choosing a unique character sequence for a given visual representation. -You can use the ``community.general.unicode_normalize`` filter to normalize ``Unicode`` strings within your playbooks. +You can use the :ansplugin:`community.general.unicode_normalize filter ` to normalize Unicode strings within your playbooks. .. code-block:: yaml+jinja @@ -28,7 +28,7 @@ This produces: "msg": true } -The ``community.general.unicode_normalize`` filter accepts a keyword argument to select the ``Unicode`` form used to normalize the input string. +The :ansplugin:`community.general.unicode_normalize filter ` accepts a keyword argument :ansopt:`community.general.unicode_normalize#filter:form` to select the Unicode form used to normalize the input string. :form: One of ``'NFC'`` (default), ``'NFD'``, ``'NFKC'``, or ``'NFKD'``. See the `Unicode reference `_ for more information. diff --git a/docs/docsite/rst/filter_guide_working_with_versions.rst b/docs/docsite/rst/filter_guide_working_with_versions.rst index 2488427b73..055bbcd217 100644 --- a/docs/docsite/rst/filter_guide_working_with_versions.rst +++ b/docs/docsite/rst/filter_guide_working_with_versions.rst @@ -6,7 +6,7 @@ Working with versions --------------------- -If you need to sort a list of version numbers, the Jinja ``sort`` filter is problematic. Since it sorts lexicographically, ``2.10`` will come before ``2.9``. To treat version numbers correctly, you can use the ``version_sort`` filter: +If you need to sort a list of version numbers, the Jinja ``sort`` filter is problematic. Since it sorts lexicographically, ``2.10`` will come before ``2.9``. To treat version numbers correctly, you can use the :ansplugin:`community.general.version_sort filter `: .. code-block:: yaml+jinja diff --git a/docs/docsite/rst/test_guide.rst b/docs/docsite/rst/test_guide.rst index b0b7885f9b..7a261c7552 100644 --- a/docs/docsite/rst/test_guide.rst +++ b/docs/docsite/rst/test_guide.rst @@ -15,7 +15,7 @@ The :ref:`community.general collection ` offers cu Feature Tests ------------- -The ``a_module`` test allows to check whether a given string refers to an existing module or action plugin. This can be useful in roles, which can use this to ensure that required modules are present ahead of time. +The :ansplugin:`community.general.a_module test ` allows to check whether a given string refers to an existing module or action plugin. This can be useful in roles, which can use this to ensure that required modules are present ahead of time. .. code-block:: yaml+jinja