diff options
author | Felix Fontein <felix@fontein.de> | 2022-09-28 15:15:53 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-09-28 08:15:53 -0500 |
commit | df0192416851244b50dfbecfc7a518248cc84c3d (patch) | |
tree | 1217840c25bcaf852387a21893caf7a6e33ef188 | |
parent | e5fd4ae7478d2c7ae085e3c99e6717525569a547 (diff) | |
download | ansible-df0192416851244b50dfbecfc7a518248cc84c3d.tar.gz |
[2.14] Improve filter docs (#78883)
(cherry picked from commit 9aa9b4eac0978f264951d1621dc95f17b5c0c0d7)
60 files changed, 290 insertions, 283 deletions
diff --git a/lib/ansible/plugins/filter/b64decode.yml b/lib/ansible/plugins/filter/b64decode.yml index af71452fcb..6edf4abf2b 100644 --- a/lib/ansible/plugins/filter/b64decode.yml +++ b/lib/ansible/plugins/filter/b64decode.yml @@ -4,22 +4,22 @@ DOCUMENTATION: version_added: 'historical' short_description: Decode a base64 string description: - - Base64 decoding function + - Base64 decoding function. positional: _input options: _input: - description: A base64 string to decode + description: A base64 string to decode. type: string required: true EXAMPLES: | # b64 decode a string - lola: "{{ 'bG9sYQ=='|b64decode }}" + lola: "{{ 'bG9sYQ==' | b64decode }}" # b64 decode the content of 'b64stuff' variable - stuff: "{{ b64stuff|b64encode }}" + stuff: "{{ b64stuff | b64encode }}" RETURN: _value: - description: the contents of the base64 encoded string + description: The contents of the base64 encoded string. type: string diff --git a/lib/ansible/plugins/filter/b64encode.yml b/lib/ansible/plugins/filter/b64encode.yml index e830d655d1..14676e515d 100644 --- a/lib/ansible/plugins/filter/b64encode.yml +++ b/lib/ansible/plugins/filter/b64encode.yml @@ -4,11 +4,11 @@ DOCUMENTATION: version_added: 'historical' short_description: Encode a string as base64 description: - - Base64 encoding function + - Base64 encoding function. positional: _input options: _input: - description: A string to encode + description: A string to encode. type: string required: true @@ -21,5 +21,5 @@ EXAMPLES: | RETURN: _value: - description: A base64 encoded string + description: A base64 encoded string. type: string diff --git a/lib/ansible/plugins/filter/basename.yml b/lib/ansible/plugins/filter/basename.yml index fdc3b4034a..4e868df804 100644 --- a/lib/ansible/plugins/filter/basename.yml +++ b/lib/ansible/plugins/filter/basename.yml @@ -7,7 +7,7 @@ DOCUMENTATION: - Returns the last name component of a path, what is left in the string that is not 'dirname'. options: _input: - description: A path + description: A path. type: path required: true seealso: diff --git a/lib/ansible/plugins/filter/bool.yml b/lib/ansible/plugins/filter/bool.yml index 571b122fe2..86ba35388f 100644 --- a/lib/ansible/plugins/filter/bool.yml +++ b/lib/ansible/plugins/filter/bool.yml @@ -3,7 +3,7 @@ DOCUMENTATION: version_added: "historical" short_description: cast into a boolean description: - - Attempt to cast the input into a boolean (C(True) or C(False)) value + - Attempt to cast the input into a boolean (C(True) or C(False)) value. positional: _input options: _input: @@ -24,5 +24,5 @@ EXAMPLES: | RETURN: _value: - description: The boolean resulting of casting the input expression into a C(True) or C(False) value + description: The boolean resulting of casting the input expression into a C(True) or C(False) value. type: bool diff --git a/lib/ansible/plugins/filter/checksum.yml b/lib/ansible/plugins/filter/checksum.yml index 9253046f2a..2f8eadd008 100644 --- a/lib/ansible/plugins/filter/checksum.yml +++ b/lib/ansible/plugins/filter/checksum.yml @@ -13,7 +13,7 @@ DOCUMENTATION: EXAMPLES: | # csum => "109f4b3c50d7b0df729d299bc6f8e9ef9066971f" - csum : {{ 'test2' | checksum }} + csum: "{{ 'test2' | checksum }}" RETURN: _value: diff --git a/lib/ansible/plugins/filter/combinations.yml b/lib/ansible/plugins/filter/combinations.yml index a2a4991bf8..a46e51e84d 100644 --- a/lib/ansible/plugins/filter/combinations.yml +++ b/lib/ansible/plugins/filter/combinations.yml @@ -17,7 +17,7 @@ DOCUMENTATION: EXAMPLES: | # combos_of_two => [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 1, 5 ], [ 2, 3 ], [ 2, 4 ], [ 2, 5 ], [ 3, 4 ], [ 3, 5 ], [ 4, 5 ] ] - combos_of_two: "{{ [1,2,3,4,5] | combinations(2) }}" + combos_of_two: "{{ [1,2,3,4,5] | combinations(2) }}" RETURN: diff --git a/lib/ansible/plugins/filter/combine.yml b/lib/ansible/plugins/filter/combine.yml index 5cd553847e..f2f4371839 100644 --- a/lib/ansible/plugins/filter/combine.yml +++ b/lib/ansible/plugins/filter/combine.yml @@ -20,7 +20,7 @@ DOCUMENTATION: type: bool default: false list_merge: - describe: Behaviour when encountering list elements. + description: Behavior when encountering list elements. type: str default: replace choices: diff --git a/lib/ansible/plugins/filter/comment.yml b/lib/ansible/plugins/filter/comment.yml index 7c264e83a3..95a4efb08e 100644 --- a/lib/ansible/plugins/filter/comment.yml +++ b/lib/ansible/plugins/filter/comment.yml @@ -3,7 +3,7 @@ DOCUMENTATION: version_added: 'historical' short_description: comment out a string description: - - Use a programmign language convention to turn the string into an embeddable comment. + - Use programming language conventions to turn the input string into an embeddable comment. positional: _input, style options: _input: @@ -25,21 +25,21 @@ DOCUMENTATION: description: Indicator the end of a comment block, only available for styles that support multiline comments. type: string newline: - description: Indicator of comment end of line, only available for styles that support multiline comments + description: Indicator of comment end of line, only available for styles that support multiline comments. type: string default: '\n' prefix: - description: Token to start each line inside a comment block, only available for styles that support multiline comments + description: Token to start each line inside a comment block, only available for styles that support multiline comments. type: string prefix_count: - description: Number of times to add a prefix at the start of a line, when a prefix exists and is usable + description: Number of times to add a prefix at the start of a line, when a prefix exists and is usable. type: int default: 1 postfix: - description: Indicator of the end of each line inside a comment block, only available for styles that support multiline comments + description: Indicator of the end of each line inside a comment block, only available for styles that support multiline comments. type: string protfix_count: - description: Number of times to add a postfix at the end of a line, when a prefix exists and is usable + description: Number of times to add a postfix at the end of a line, when a prefix exists and is usable. type: int default: 1 diff --git a/lib/ansible/plugins/filter/difference.yml b/lib/ansible/plugins/filter/difference.yml index b3237fb12f..decc811a19 100644 --- a/lib/ansible/plugins/filter/difference.yml +++ b/lib/ansible/plugins/filter/difference.yml @@ -7,11 +7,11 @@ DOCUMENTATION: - Provide a unique list of all the elements of the first list that do not appear in the second one. options: _input: - description: A list + description: A list. type: list required: true _second_list: - description: A list + description: A list. type: list required: true seealso: @@ -31,5 +31,5 @@ EXAMPLES: | # => [10] RETURN: _value: - description: A unique list of the elements from the first list that do not appear on the 2nd + description: A unique list of the elements from the first list that do not appear on the second. type: list diff --git a/lib/ansible/plugins/filter/dirname.yml b/lib/ansible/plugins/filter/dirname.yml index ce7f1ffb93..52f7d5d42e 100644 --- a/lib/ansible/plugins/filter/dirname.yml +++ b/lib/ansible/plugins/filter/dirname.yml @@ -7,7 +7,7 @@ DOCUMENTATION: - Returns the 'head' component of a path, basically everything that is not the 'basename'. options: _input: - description: A path + description: A path. type: path required: true seealso: diff --git a/lib/ansible/plugins/filter/expanduser.yml b/lib/ansible/plugins/filter/expanduser.yml index 62df699741..2aff468777 100644 --- a/lib/ansible/plugins/filter/expanduser.yml +++ b/lib/ansible/plugins/filter/expanduser.yml @@ -2,9 +2,9 @@ DOCUMENTATION: name: basename author: ansible core team version_added: "1.5" - short_description: Returns a path with '~' translation. + short_description: Returns a path with C(~) translation. description: - - Translates `~` in a path to the proper user's home directory. + - Translates C(~) in a path to the proper user's home directory. options: _input: description: A string that contains a path. diff --git a/lib/ansible/plugins/filter/extract.yml b/lib/ansible/plugins/filter/extract.yml index 8637e00e4d..2b4989d15b 100644 --- a/lib/ansible/plugins/filter/extract.yml +++ b/lib/ansible/plugins/filter/extract.yml @@ -13,7 +13,7 @@ DOCUMENTATION: type: raw required: true contianer: - description: dictionary or list from which to extract a value + description: Dictionary or list from which to extract a value. type: raw required: true morekeys: diff --git a/lib/ansible/plugins/filter/fileglob.yml b/lib/ansible/plugins/filter/fileglob.yml index e2d2574ddc..69e8a9b2aa 100644 --- a/lib/ansible/plugins/filter/fileglob.yml +++ b/lib/ansible/plugins/filter/fileglob.yml @@ -2,8 +2,8 @@ DOCUMENTATION: name: fileglob short_description: explode a path glob to matching files description: - - return a list of files that matches the supplied path glob pattern - - filters run on the controller, so the files are matched from the controller's file system + - Return a list of files that matches the supplied path glob pattern. + - Filters run on the controller, so the files are matched from the controller's file system. positional: _input options: _input: @@ -19,3 +19,4 @@ RETURN: _value: description: List of files matched. type: list + elements: string diff --git a/lib/ansible/plugins/filter/from_json.yml b/lib/ansible/plugins/filter/from_json.yml index 33dfc9c886..4edc2bd3d7 100644 --- a/lib/ansible/plugins/filter/from_json.yml +++ b/lib/ansible/plugins/filter/from_json.yml @@ -4,7 +4,7 @@ DOCUMENTATION: short_description: Convert JSON string into variable structure description: - Converts a JSON string representation into an equivalent structured Ansible variable. - - Ansible internally auto-converts JSON strings into variable structures in most contexts, this plugin is used for those contexts it doesn't. + - Ansible automatically converts JSON strings into variable structures in most contexts, use this plugin in contexts where automatic conversion does not happen. notes: - This filter functions as a wrapper to the Python C(json.loads) function. options: diff --git a/lib/ansible/plugins/filter/from_yaml.yml b/lib/ansible/plugins/filter/from_yaml.yml index 5bfcfcfa99..e9b1599734 100644 --- a/lib/ansible/plugins/filter/from_yaml.yml +++ b/lib/ansible/plugins/filter/from_yaml.yml @@ -4,9 +4,9 @@ DOCUMENTATION: short_description: Convert YAML string into variable structure description: - Converts a YAML string representation into an equivalent structured Ansible variable. - - Ansible internally auto-converts YAML strings into variable structures in most contexts, this plugin is used for those contexts it doesn't. + - Ansible automatically converts YAML strings into variable structures in most contexts, use this plugin in contexts where automatic conversion does not happen. notes: - - This filter functions as a wrapper to the Python pyyaml library's ``yaml.safe_load()`` function. + - This filter functions as a wrapper to the L(Python pyyaml library, https://pypi.org/project/PyYAML/)'s C(yaml.safe_load) function. options: _input: description: A YAML string. @@ -21,5 +21,5 @@ EXAMPLES: | RETURN: _value: - description: the variable resuliting from deserializing the YAML document. + description: The variable resulting from deserializing the YAML document. type: raw diff --git a/lib/ansible/plugins/filter/from_yaml_all.yml b/lib/ansible/plugins/filter/from_yaml_all.yml index a823615c09..b179f1cb85 100644 --- a/lib/ansible/plugins/filter/from_yaml_all.yml +++ b/lib/ansible/plugins/filter/from_yaml_all.yml @@ -7,7 +7,7 @@ DOCUMENTATION: - Ansible internally auto-converts YAML strings into variable structures in most contexts, but by default does not handle 'multi document' YAML files or strings. - If multiple YAML documents are not supplied, this is the equivalend of using C(from_yaml). notes: - - This filter functions as a wrapper to the Python ``yaml.safe_load_all()`` function, part of the pyyaml python library + - This filter functions as a wrapper to the Python C(yaml.safe_load_all) function, part of the L(pyyaml Python library, https://pypi.org/project/PyYAML/). - Possible conflicts in variable names from the mulitple documents are resolved directly by the pyyaml library. options: _input: @@ -24,5 +24,5 @@ EXAMPLES: | RETURN: _value: - description: the variable resuliting from deserializing the YAML documents. + description: The variable resulting from deserializing the YAML documents. type: raw diff --git a/lib/ansible/plugins/filter/hash.yml b/lib/ansible/plugins/filter/hash.yml index e87acc726c..0f5f315cc5 100644 --- a/lib/ansible/plugins/filter/hash.yml +++ b/lib/ansible/plugins/filter/hash.yml @@ -3,17 +3,17 @@ DOCUMENTATION: version_added: "1.9" short_description: hash of input data description: - - Returns a configurable hash (sha1) hash of the input data + - Returns a configurable hash of the input data. Uses L(SHA-1, https://en.wikipedia.org/wiki/SHA-1) by default. positional: _input options: _input: - description: data to checksum + description: Data to checksum. type: raw required: true hashtype: description: - - type of algorighim to produce the hash - - the list of available choices depends on the installed Python's hashlib + - Type of algorithm to produce the hash. + - The list of available choices depends on the installed Python's hashlib. type: string default: sha1 EXAMPLES: | @@ -24,5 +24,5 @@ EXAMPLES: | RETURN: _value: - description: The checksum (sha1) of the input + description: The checksum of the input, as configured in I(hashtype). type: string diff --git a/lib/ansible/plugins/filter/human_readable.yml b/lib/ansible/plugins/filter/human_readable.yml index 95db5ccade..e3028ac549 100644 --- a/lib/ansible/plugins/filter/human_readable.yml +++ b/lib/ansible/plugins/filter/human_readable.yml @@ -3,32 +3,33 @@ DOCUMENTATION: version_added: "historical" short_description: Make bytes/bits human readable description: - - Convert byte or bit figures to more human readable formats + - Convert byte or bit figures to more human readable formats. positional: _input, isbits, unit options: _input: - description: bytes + description: Number of bytes, or bits. Depends on I(isbits). type: int required: true - isbits: - description: input is bits, instead of bytes + isbits: + description: Whether the input is bits, instead of bytes. type: bool - unit: - description: unit to force output into, if none specified the largest unit arrived at will be used + default: false + unit: + description: Unit to force output into. If none specified the largest unit arrived at will be used. type: str choices: [ 'Y', 'Z', 'E', 'P', 'T', 'G', 'M', 'K', 'B'] EXAMPLES: | # size => "1.15 GB" - size: "{{ 1232345345|human_readable }}" + size: "{{ 1232345345 | human_readable }}" # size => "1.15 Gb" - size_bits: "{{ 1232345345|human_readable(true) }}" + size_bits: "{{ 1232345345 | human_readable(true) }}" # size => "1175.26 MB" - size_MB: "{{ 1232345345|human_readable(unit='M') }}" + size_MB: "{{ 1232345345 | human_readable(unit='M') }}" RETURN: _value: - description: human readable byte or bit size + description: Human readable byte or bit size. type: str diff --git a/lib/ansible/plugins/filter/human_to_bytes.yml b/lib/ansible/plugins/filter/human_to_bytes.yml index ea19ae95f2..f03deedb33 100644 --- a/lib/ansible/plugins/filter/human_to_bytes.yml +++ b/lib/ansible/plugins/filter/human_to_bytes.yml @@ -3,19 +3,19 @@ DOCUMENTATION: version_added: "historical" short_description: Get bytes from string description: - - Convert a human readable byte or bit string into a number bytes + - Convert a human readable byte or bit string into a number bytes. positional: _input, default_unit, isbits options: _input: - description: bytes + description: Human readable description of a number of bytes. type: int required: true - default_unit: - description: unit to assume when input does not specify it + default_unit: + description: Unit to assume when input does not specify it. type: str choices: ['Y', 'Z', 'E', 'P', 'T', 'G', 'M', 'K', 'B'] - isbits: - description: if C(True) force to interpet only bit input, if C(False) force bytes, otherwise just use the notation to guess + isbits: + description: If C(True), force to interpret only bit input; if C(False), force bytes. Otherwise use the notation to guess. type: bool EXAMPLES: | @@ -30,5 +30,5 @@ EXAMPLES: | RETURN: _value: - description: integer representing the bytes from the input + description: Integer representing the bytes from the input. type: int diff --git a/lib/ansible/plugins/filter/intersect.yml b/lib/ansible/plugins/filter/intersect.yml index 4be56d2952..d811ecaaf0 100644 --- a/lib/ansible/plugins/filter/intersect.yml +++ b/lib/ansible/plugins/filter/intersect.yml @@ -7,11 +7,11 @@ DOCUMENTATION: - Provide a list with the common elements from other lists. options: _input: - description: A list + description: A list. type: list required: true _second_list: - description: A list + description: A list. type: list required: true seealso: @@ -31,5 +31,5 @@ EXAMPLES: | # => [1, 2, 5, 3, 4] RETURN: _value: - description: A list with unique elements common to both lists, also known as a set + description: A list with unique elements common to both lists, also known as a set. type: list diff --git a/lib/ansible/plugins/filter/items2dict.yml b/lib/ansible/plugins/filter/items2dict.yml index d93eba92d1..1352c6742d 100644 --- a/lib/ansible/plugins/filter/items2dict.yml +++ b/lib/ansible/plugins/filter/items2dict.yml @@ -16,11 +16,11 @@ DOCUMENTATION: elements: dict required: true key_name: - description: The name of the key in the element dictionaries that holds the key to use at destination + description: The name of the key in the element dictionaries that holds the key to use at destination. type: str default: key value_name: - description: The name of the key in the element dictionaries that holds the value to use at destination + description: The name of the key in the element dictionaries that holds the value to use at destination. type: str default: value seealso: @@ -44,5 +44,5 @@ EXAMPLES: | RETURN: _value: - description: dictionary with the consolidated key/values + description: Dictionary with the consolidated key/values. type: dict diff --git a/lib/ansible/plugins/filter/log.yml b/lib/ansible/plugins/filter/log.yml index ca59696f7f..c7bb70451b 100644 --- a/lib/ansible/plugins/filter/log.yml +++ b/lib/ansible/plugins/filter/log.yml @@ -3,19 +3,20 @@ DOCUMENTATION: version_added: "1.9" short_description: log of (math operation) description: - - math operation that returns the N logarithim of inputed number logN(X) + - Math operation that returns the L(logarithm, https://en.wikipedia.org/wiki/Logarithm) to base N of the input number. + - By default, computes the L(natural logarithm, https://en.wikipedia.org/wiki/Natural_logarithm). notes: - - This is a passthrough to Python's C(math.log) + - This is a passthrough to Python's C(math.log). positional: _input, base options: _input: - description: number to operate on - type: int + description: Number to operate on. + type: float required: true base: - description: which base to use - type: int - default: 10 + description: Which base to use. Defaults to L(Euler's number, https://en.wikipedia.org/wiki/Euler%27s_number). + type: float + default: 2.718281828459045 EXAMPLES: | @@ -28,5 +29,5 @@ EXAMPLES: | RETURN: _value: - description: resulting number - type: int + description: Resulting number. + type: float diff --git a/lib/ansible/plugins/filter/mandatory.yml b/lib/ansible/plugins/filter/mandatory.yml index 878a240e53..5addf15986 100644 --- a/lib/ansible/plugins/filter/mandatory.yml +++ b/lib/ansible/plugins/filter/mandatory.yml @@ -1,21 +1,21 @@ DOCUMENTATION: name: mandatory version_added: "historical" - short_description: make a varaible's existance mandatory + short_description: make a variable's existance mandatory description: - Depending on context undefined variables can be ignored or skipped, this ensures they force an error. positional: _input options: _input: - description: mandatory expression + description: Mandatory expression. type: raw required: true EXAMPLES: | # results in a Filter Error - {{ notdefined | mandatory}} + {{ notdefined | mandatory }} RETURN: _value: - description: the input if defined, otherwise an error + description: The input if defined, otherwise an error. type: raw diff --git a/lib/ansible/plugins/filter/md5.yml b/lib/ansible/plugins/filter/md5.yml index 02993dfd5d..c97870d086 100644 --- a/lib/ansible/plugins/filter/md5.yml +++ b/lib/ansible/plugins/filter/md5.yml @@ -1,12 +1,12 @@ DOCUMENTATION: name: md5 version_added: "historical" - short_description: md5 hash of input data + short_description: MD5 hash of input data description: - - Returns a md5 hash of the input data + - Returns an L(MD5 hash, https://en.wikipedia.org/wiki/MD5) of the input data positional: _input notes: - - This requires the md5 algorithim to be available on the system, security contexts like FIPS might prevent this. + - This requires the MD5 algorithm to be available on the system, security contexts like FIPS might prevent this. - MD5 has long been deemed insecure and is not recommended for security related uses. options: _input: @@ -20,5 +20,5 @@ EXAMPLES: | RETURN: _value: - description: The md5 hash of the input + description: The MD5 hash of the input. type: string diff --git a/lib/ansible/plugins/filter/password_hash.yml b/lib/ansible/plugins/filter/password_hash.yml index 37f72a2c02..d12efb4c6a 100644 --- a/lib/ansible/plugins/filter/password_hash.yml +++ b/lib/ansible/plugins/filter/password_hash.yml @@ -3,35 +3,35 @@ DOCUMENTATION: version_added: "historical" short_description: convert input password into password_hash description: - - Returns a password_hash of a secret + - Returns a password_hash of a secret. positional: _input notes: - - Algorithims available might be restricted by the system + - Algorithms available might be restricted by the system. options: _input: - description: secret to hash + description: Secret to hash. type: string required: true hashtype: - description: hashing algorithm to use + description: Hashing algorithm to use. type: string default: sha512 choices: [ md5, blowfish, sha256, sha512 ] salt: - description: secret string that is used for the hashing, if none is provided a random one can be generated + description: Secret string that is used for the hashing, if none is provided a random one can be generated. type: int rounds: - description: number of encryption rounds, default varies by algorithim used + description: Number of encryption rounds, default varies by algorithm used. type: int ident: - description: no clue - type: string? + description: Algorithm identifier. + type: string EXAMPLES: | # pwdhash => "$6$/bQCntzQ7VrgVcFa$VaMkmevkY1dqrx8neaenUDlVU.6L/.ojRbrnI4ID.yBHU6XON1cB422scCiXfUL5wRucMdLgJU0Fn38uoeBni/" - pwdhash: "{{ 'testing' | password_hash}}" + pwdhash: "{{ 'testing' | password_hash }}" RETURN: _value: - description: The resulting password hash + description: The resulting password hash. type: string diff --git a/lib/ansible/plugins/filter/permutations.yml b/lib/ansible/plugins/filter/permutations.yml index 24083086ab..6e0202bce3 100644 --- a/lib/ansible/plugins/filter/permutations.yml +++ b/lib/ansible/plugins/filter/permutations.yml @@ -3,16 +3,16 @@ DOCUMENTATION: version_added: "historical" short_description: permutations from the elements of a list description: - - Create a list of the permutations of lists from the elements of a list - - Unlke combinations, in permutations order is significant + - Create a list of the permutations of lists from the elements of a list. + - Unlike combinations, in permutations order is significant. positional: _input, list_size options: _input: - description: elements to base the permutations on + description: Elements to base the permutations on. type: list required: true list_size: - description: the size of the list for each permutation + description: The size of the list for each permutation. type: int required: true @@ -22,5 +22,5 @@ EXAMPLES: | RETURN: _value: - description: list of permutations lists resulting from the supplied elements and list size + description: List of permutations lists resulting from the supplied elements and list size. type: list diff --git a/lib/ansible/plugins/filter/pow.yml b/lib/ansible/plugins/filter/pow.yml index 865951ab8b..da2fa42739 100644 --- a/lib/ansible/plugins/filter/pow.yml +++ b/lib/ansible/plugins/filter/pow.yml @@ -3,18 +3,18 @@ DOCUMENTATION: version_added: "1.9" short_description: power of (math operation) description: - - math operation that returns the N power of inputed number X ^ N + - Math operation that returns the Nth power of inputed number, C(X ^ N). notes: - - This is a passthrough to Python's C(itertools.product) + - This is a passthrough to Python's C(math.pow). positional: _input, _power options: _input: - description: number to power up! - type: int + description: The base. + type: float required: true _power: - description: which power to use - type: int + description: Which power (exponent) to use. + type: float required: true EXAMPLES: | @@ -30,5 +30,5 @@ EXAMPLES: | RETURN: _value: - description: resulting number - type: int + description: Resulting number. + type: float diff --git a/lib/ansible/plugins/filter/product.yml b/lib/ansible/plugins/filter/product.yml index 3a5b528b4f..c558e4e426 100644 --- a/lib/ansible/plugins/filter/product.yml +++ b/lib/ansible/plugins/filter/product.yml @@ -3,22 +3,22 @@ DOCUMENTATION: version_added: "historical" short_description: cartesian product of lists description: - - Combines two lists into one with each element being the product of the elements of the input lists - - this is an effective way to create 'nested loops', looping over C(listA) and C(listB) is the same as looping over C(listA|product(listB)) + - Combines two lists into one with each element being the product of the elements of the input lists. + - Creates 'nested loops'. Looping over C(listA) and C(listB) is the same as looping over C(listA | product(listB)). notes: - This is a passthrough to Python's C(itertools.product) positional: _input, _additional_lists, repeat options: _input: - description: first list + description: First list. type: list required: true _additional_lists: #TODO: *args, N possible additional lists - description: addional list for the product + description: Additional list for the product. type: list required: false repeat: - description: number of times to repeat the product against itself + description: Number of times to repeat the product against itself. default: 1 type: int EXAMPLES: | @@ -37,5 +37,6 @@ EXAMPLES: | RETURN: _value: - description: list of lists of combined elements from the input lists + description: List of lists of combined elements from the input lists. type: list + elements: list diff --git a/lib/ansible/plugins/filter/quote.yml b/lib/ansible/plugins/filter/quote.yml index 08820a9a43..2d621ed065 100644 --- a/lib/ansible/plugins/filter/quote.yml +++ b/lib/ansible/plugins/filter/quote.yml @@ -3,21 +3,21 @@ DOCUMENTATION: version_added: "2.10" short_description: shell quoting description: - - Quote a string to safely use as in a POSIX shell + - Quote a string to safely use as in a POSIX shell. notes: - - This is a passthrough to Python's C(shelex.quote) + - This is a passthrough to Python's C(shlex.quote). positional: _input options: _input: - description: string to quote + description: String to quote. type: str required: true -EXAMPLES: +EXAMPLES: | - name: Run a shell command shell: echo {{ string_value | quote }} RETURN: _value: - description: quoted string + description: Quoted string. type: str diff --git a/lib/ansible/plugins/filter/random.yml b/lib/ansible/plugins/filter/random.yml index 4b6dd3fcb5..b72dbb292b 100644 --- a/lib/ansible/plugins/filter/random.yml +++ b/lib/ansible/plugins/filter/random.yml @@ -3,24 +3,22 @@ DOCUMENTATION: version_added: "2.6" short_description: random number or list item description: - - Use the intput to either select a random element of a list or generate a random number - notes: - - This is a passthrough to Python's C(shelex.quote) + - Use the input to either select a random element of a list or generate a random number. positional: _input, start, step, seed options: _input: - description: A number or list/sequence, if it is a number it is the top bound for random number generation, if it is a sequence or list, the source of the random element selected + description: A number or list/sequence, if it is a number it is the top bound for random number generation, if it is a sequence or list, the source of the random element selected. type: raw required: true start: - description: bottom bound for the random number/element generated + description: Bottom bound for the random number/element generated. type: int step: - description: subsets the defined range by only using this value to select the increments of it between start and end + description: Subsets the defined range by only using this value to select the increments of it between start and end. type: int default: 1 seed: - description: if specified use a pseudo random selection instead (repeatable) + description: If specified use a pseudo random selection instead (repeatable). type: str EXAMPLES: | @@ -33,5 +31,5 @@ EXAMPLES: | RETURN: _value: - description: random number or list element + description: Random number or list element. type: raw diff --git a/lib/ansible/plugins/filter/regex_escape.yml b/lib/ansible/plugins/filter/regex_escape.yml index fba5725729..78199097db 100644 --- a/lib/ansible/plugins/filter/regex_escape.yml +++ b/lib/ansible/plugins/filter/regex_escape.yml @@ -3,17 +3,17 @@ DOCUMENTATION: version_added: "2.8" short_description: escape regex chars description: - - Escape special characters in a string for use in a regular expression + - Escape special characters in a string for use in a regular expression. positional: _input, re_type notes: - posix_extended is not implemented yet options: _input: - description: String to escape + description: String to escape. type: str required: true re_type: - description: Which type of escaping to use + description: Which type of escaping to use. type: str default: python choices: [python, posix_basic] @@ -25,5 +25,5 @@ EXAMPLES: | RETURN: _value: - description: escaped string + description: Escaped string. type: str diff --git a/lib/ansible/plugins/filter/regex_findall.yml b/lib/ansible/plugins/filter/regex_findall.yml index a1cea0773c..707d6fa1e9 100644 --- a/lib/ansible/plugins/filter/regex_findall.yml +++ b/lib/ansible/plugins/filter/regex_findall.yml @@ -3,22 +3,22 @@ DOCUMENTATION: version_added: "2.0" short_description: extract all regex matches from string description: - - Search in a string or extract all the parts of a string matching a regular expression + - Search in a string or extract all the parts of a string matching a regular expression. positional: _input, _regex options: _input: - description: String to match against + description: String to match against. type: str required: true _regex: - description: regular expression string that defines the match + description: Regular expression string that defines the match. type: str multiline: - description: search across line endings if C(True), don't if otherwise + description: Search across line endings if C(True), do not if otherwise. type: bool default: no ignorecase: - description: force the serach to be case insensitive if C(True), case senstitive otherwise + description: Force the search to be case insensitive if C(True), case sensitive otherwise. type: bool default: no @@ -32,6 +32,6 @@ EXAMPLES: | RETURN: _value: - description: list of matched strings + description: List of matched strings. type: list elements: str diff --git a/lib/ansible/plugins/filter/regex_replace.yml b/lib/ansible/plugins/filter/regex_replace.yml index 327c2a54c5..bb9460cc28 100644 --- a/lib/ansible/plugins/filter/regex_replace.yml +++ b/lib/ansible/plugins/filter/regex_replace.yml @@ -3,29 +3,29 @@ DOCUMENTATION: version_added: "2.0" short_description: replace a string via regex description: - - Replace a substring defined by a regular expression with another defined by another regular expressoin based on the first match + - Replace a substring defined by a regular expression with another defined by another regular expressoin based on the first match. notes: - - Maps to Python's C(regex.replace) + - Maps to Python's C(regex.replace). positional: _input, _regex_match, _regex_replace options: _input: - description: String to match against + description: String to match against. type: str required: true _regex_match: - description: regular expression string that defines the match + description: Regular expression string that defines the match. type: int required: true _regex_replace: - description: regular expression string that defines the replacement + description: Regular expression string that defines the replacement. type: int required: true multiline: - description: search across line endings if C(True), don't if otherwise + description: Search across line endings if C(True), do not if otherwise. type: bool default: no ignorecase: - description: force the serach to be case insensitive if C(True), case senstitive otherwise + description: Force the search to be case insensitive if C(True), case sensitive otherwise. type: bool default: no @@ -42,5 +42,5 @@ EXAMPLES: | RETURN: _value: - description: string with substitution (or original if no match) + description: String with substitution (or original if no match). type: str diff --git a/lib/ansible/plugins/filter/regex_search.yml b/lib/ansible/plugins/filter/regex_search.yml index dee89ed81d..b459c93699 100644 --- a/lib/ansible/plugins/filter/regex_search.yml +++ b/lib/ansible/plugins/filter/regex_search.yml @@ -3,24 +3,24 @@ DOCUMENTATION: version_added: "2.0" short_description: extract regex match from string description: - - Search in a string to extract the part that matches the regular expression + - Search in a string to extract the part that matches the regular expression. notes: - - Maps to Python's C(regex.search) + - Maps to Python's C(regex.search). positional: _input, _regex options: _input: - description: String to match against + description: String to match against. type: str required: true _regex: - description: regular expression string that defines the match + description: Regular expression string that defines the match. type: str multiline: - description: search across line endings if C(True), don't if otherwise + description: Search across line endings if C(True), do not if otherwise. type: bool default: no ignorecase: - description: force the serach to be case insensitive if C(True), case senstitive otherwise + description: Force the search to be case insensitive if C(True), case sensitive otherwise. type: bool default: no @@ -34,5 +34,5 @@ EXAMPLES: | RETURN: _value: - description: matched string or empty string if no match + description: Matched string or empty string if no match. type: str diff --git a/lib/ansible/plugins/filter/rekey_on_member.yml b/lib/ansible/plugins/filter/rekey_on_member.yml index de0e02fe4e..d7470ab97e 100644 --- a/lib/ansible/plugins/filter/rekey_on_member.yml +++ b/lib/ansible/plugins/filter/rekey_on_member.yml @@ -3,20 +3,18 @@ DOCUMENTATION: version_added: "2.13" short_description: Rekey a list of dicts into a dict using a member positional: _input, '_key', duplicates - description: Iterate over several iterables in parallel, producing tuples with an item from each one - notes: - - This is mostly a passhtrough to Python's C(zip) function + description: Iterate over several iterables in parallel, producing tuples with an item from each one. options: _input: - description: Original dictionary + description: Original dictionary. type: dict required: yes _key: - description: The key to rekey + description: The key to rekey. type: str required: yes duplicates: - description: how to handle duplilcates + description: How to handle duplicates. type: str default: error choices: [overwrite, error] @@ -28,5 +26,5 @@ EXAMPLES: | RETURN: _value: - description: the resulting dictionary + description: The resulting dictionary. type: dict diff --git a/lib/ansible/plugins/filter/relpath.yml b/lib/ansible/plugins/filter/relpath.yml index 39177ca8f1..47611c7658 100644 --- a/lib/ansible/plugins/filter/relpath.yml +++ b/lib/ansible/plugins/filter/relpath.yml @@ -5,7 +5,7 @@ DOCUMENTATION: short_description: Make a path relative positional: _input, start description: - - Converts the given path to a relative path from the C(start). + - Converts the given path to a relative path from the I(start), or relative to the directory given in I(start). options: _input: @@ -13,7 +13,7 @@ DOCUMENTATION: type: str required: true start: - description: The directory the path should be relative to. if not supplied the current working directory will be used + description: The directory the path should be relative to. If not supplied the current working directory will be used. type: str EXAMPLES: | diff --git a/lib/ansible/plugins/filter/root.yml b/lib/ansible/plugins/filter/root.yml index 6bc061cf70..4f52590bb8 100644 --- a/lib/ansible/plugins/filter/root.yml +++ b/lib/ansible/plugins/filter/root.yml @@ -3,16 +3,16 @@ DOCUMENTATION: version_added: "1.9" short_description: root of (math operation) description: - - math operation that returns the N root of inputed number X ^^ N + - Math operation that returns the Nth root of inputed number C(X ^^ N). positional: _input, base options: _input: - description: number to operate on - type: int + description: Number to operate on. + type: float required: true base: - description: which base to use - type: int + description: Which root to take. + type: float default: 2 EXAMPLES: | @@ -28,5 +28,5 @@ EXAMPLES: | RETURN: _value: - description: resulting number - type: int + description: Resulting number. + type: float diff --git a/lib/ansible/plugins/filter/sha1.yml b/lib/ansible/plugins/filter/sha1.yml index 55776d86a3..f80803b4a1 100644 --- a/lib/ansible/plugins/filter/sha1.yml +++ b/lib/ansible/plugins/filter/sha1.yml @@ -1,16 +1,16 @@ DOCUMENTATION: name: sha1 version_added: "historical" - short_description: sha1 hash of input data + short_description: SHA-1 hash of input data description: - - Returns a sha1 hash of the input data + - Returns a L(SHA-1 hash, https://en.wikipedia.org/wiki/SHA-1) of the input data. positional: _input notes: - - This requires the md5 algorithim to be available on the system, security contexts like FIPS might prevent this. - - SHA1 has been deemed insecure and is not recommended for security related uses. + - This requires the SHA-1 algorithm to be available on the system, security contexts like FIPS might prevent this. + - SHA-1 has been deemed insecure and is not recommended for security related uses. options: _input: - description: data to hash + description: Data to hash. type: raw required: true @@ -20,5 +20,5 @@ EXAMPLES: | RETURN: _value: - description: The sha1 hash of the input + description: The SHA-1 hash of the input. type: string diff --git a/lib/ansible/plugins/filter/shuffle.yml b/lib/ansible/plugins/filter/shuffle.yml index affe2b7404..a7c3e7ed22 100644 --- a/lib/ansible/plugins/filter/shuffle.yml +++ b/lib/ansible/plugins/filter/shuffle.yml @@ -3,25 +3,25 @@ DOCUMENTATION: version_added: "2.6" short_description: randomize a list description: - - Take the elements of the input list and return in a random order + - Take the elements of the input list and return in a random order. positional: _input options: _input: - description: A number or list to randomize + description: A number or list to randomize. type: list elements: any required: true seed: - description: if specified use a pseudo random selection instead (repeatable) + description: If specified use a pseudo random selection instead (repeatable). type: str -EXAMPLES: +EXAMPLES: | randomized_list: "{{ ['a','b','c'] | shuffle}}" per_host_repeatable: "{{ ['a','b','c'] | shuffle(seed=inventory_hostname) }}" RETURN: _value: - description: random number or list element + description: Random number or list element. type: list elements: any diff --git a/lib/ansible/plugins/filter/split.yml b/lib/ansible/plugins/filter/split.yml index 7ba02da9a3..3e7b59ec3d 100644 --- a/lib/ansible/plugins/filter/split.yml +++ b/lib/ansible/plugins/filter/split.yml @@ -3,21 +3,21 @@ DOCUMENTATION: version_added: "historical" short_description: split a string into a list description: - - Using Python's text object method C(split()) we turn strings into lists via a 'spliting character'. + - Using Python's text object method C(split) we turn strings into lists via a 'spliting character'. notes: - - This is a passthrough to Python's C(shelex.quote) + - This is a passthrough to Python's C(str.split). positional: _input, _split_string options: _input: - description: A string to split + description: A string to split. type: str required: true _split_string: - description: a string on which to split the original + description: A string on which to split the original. type: str default: ' ' -EXAMPLES: +EXAMPLES: | # listjojo => [ "jojo", "is", "a" ] listjojo: "{{ 'jojo is a' | split }}" @@ -27,6 +27,6 @@ EXAMPLES: RETURN: _value: - description: list of substrings split from the original + description: List of substrings split from the original. type: list elements: str diff --git a/lib/ansible/plugins/filter/splitext.yml b/lib/ansible/plugins/filter/splitext.yml index 64d9662e20..ea9cbcec31 100644 --- a/lib/ansible/plugins/filter/splitext.yml +++ b/lib/ansible/plugins/filter/splitext.yml @@ -5,7 +5,7 @@ DOCUMENTATION: short_description: split a path into root and file extension positional: _input description: - - Returns a list of two, with the elements consisting filename root and extension + - Returns a list of two, with the elements consisting of filename root and extension. options: _input: description: A path. diff --git a/lib/ansible/plugins/filter/strftime.yml b/lib/ansible/plugins/filter/strftime.yml index 7a51757343..6cb8874ad5 100644 --- a/lib/ansible/plugins/filter/strftime.yml +++ b/lib/ansible/plugins/filter/strftime.yml @@ -3,20 +3,22 @@ DOCUMENTATION: version_added: "2.4" short_description: date formating description: - - Using Python's stftime function, take a data formating string and a date/time to create a formated date. + - Using Python's C(strftime) function, take a data formating string and a date/time to create a formated date. notes: - - This is a passthrough to Python's C(shelex.quote) + - This is a passthrough to Python's C(stftime). positional: _input, second, utc options: _input: - description: A formating string following stftime convetions + description: + - A formating string following C(stftime) conventions. + - See L(the Python documentation, https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior) for a reference. type: str required: true second: - description: datetime in seconds from C(epoch) to format, if not suplied C(gmttime()/localtime()) will be used + description: Datetime in seconds from C(epoch) to format, if not supplied C(gmttime/localtime) will be used. type: int utc: - description: if time supplied is in UTC + description: Whether time supplied is in UTC. type: bool default: false @@ -39,5 +41,5 @@ EXAMPLES: | RETURN: _value: - description: a formated date/time + description: A formatted date/time string. type: str diff --git a/lib/ansible/plugins/filter/subelements.yml b/lib/ansible/plugins/filter/subelements.yml index 5de9a53b2f..a2d1a9402e 100644 --- a/lib/ansible/plugins/filter/subelements.yml +++ b/lib/ansible/plugins/filter/subelements.yml @@ -4,19 +4,19 @@ DOCUMENTATION: short_description: retuns a product of a list and it's elements positional: _input, _subelement, skip_missing description: - - This produces a product of an object and the subelement values of that object, similar to the subelements lookup. This lets you specify individual subelements to use in a template _input + - This produces a product of an object and the subelement values of that object, similar to the subelements lookup. This lets you specify individual subelements to use in a template I(_input). options: _input: - description: Original list + description: Original list. type: list elements: any required: yes _subelement: - description: Label of property to extract from original list items + description: Label of property to extract from original list items. type: str required: yes skip_missing: - description: if C(True), ignore missing subelements, otherwise it is an error. + description: If C(True), ignore missing subelements, otherwise missing subelements generate an error. type: bool default: no @@ -33,6 +33,6 @@ EXAMPLES: | RETURN: _value: - description: list made of original list and product of the subelement list + description: List made of original list and product of the subelement list. type: list elements: any diff --git a/lib/ansible/plugins/filter/symmetric_difference.yml b/lib/ansible/plugins/filter/symmetric_difference.yml index 27541f6b5a..de4f3c6b39 100644 --- a/lib/ansible/plugins/filter/symmetric_difference.yml +++ b/lib/ansible/plugins/filter/symmetric_difference.yml @@ -2,16 +2,16 @@ DOCUMENTATION: name: symmetric_difference author: Brian Coca (@bcoca) version_added: "1.4" - short_description: different items from 2 lists + short_description: different items from two lists description: - Provide a unique list of all the elements unique to each list. options: _input: - description: A list + description: A list. type: list required: true _second_list: - description: A list + description: A list. type: list required: true seealso: @@ -31,5 +31,5 @@ EXAMPLES: | # => [10, 11, 99] RETURN: _value: - description: A unique list of the elements from 2 lists that are unique to each one + description: A unique list of the elements from two lists that are unique to each one. type: list diff --git a/lib/ansible/plugins/filter/ternary.yml b/lib/ansible/plugins/filter/ternary.yml index 47c48d7a18..50ff767678 100644 --- a/lib/ansible/plugins/filter/ternary.yml +++ b/lib/ansible/plugins/filter/ternary.yml @@ -23,7 +23,7 @@ DOCUMENTATION: type: any version_added: '2.8' notes: - - vars as values are evaluated even if not returned. This is due to them being evaluated before being passed into the filter. + - Vars as values are evaluated even when not returned. This is due to them being evaluated before being passed into the filter. EXAMPLES: | # set first 10 volumes rw, rest as dp diff --git a/lib/ansible/plugins/filter/to_datetime.yml b/lib/ansible/plugins/filter/to_datetime.yml index d3d0af2d17..dbd476a1d8 100644 --- a/lib/ansible/plugins/filter/to_datetime.yml +++ b/lib/ansible/plugins/filter/to_datetime.yml @@ -1,19 +1,20 @@ DOCUMENTATION: name: to_datetime version_added: "2.4" - short_description: Get datetime from string + short_description: Get C(datetime) from string description: - - Using the input string attempt to create a matching Python datetime object + - Using the input string attempt to create a matching Python C(datetime) object. notes: - - For a full list of format codes for working with python date format strings, see https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior. + - For a full list of format codes for working with Python date format strings, see + L(the Python documentation, https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior). positional: _input options: _input: - description: A string containing date time information + description: A string containing date time information. type: str required: true format: - description: strformat formated string that describes the expected format of the input string + description: C(strformat) formatted string that describes the expected format of the input string. type: str EXAMPLES: | @@ -30,5 +31,5 @@ EXAMPLES: | RETURN: _value: - description: datetime object from the represented value + description: C(datetime) object from the represented value. type: raw diff --git a/lib/ansible/plugins/filter/to_json.yml b/lib/ansible/plugins/filter/to_json.yml index c28dba43ab..6f32d7c7d3 100644 --- a/lib/ansible/plugins/filter/to_json.yml +++ b/lib/ansible/plugins/filter/to_json.yml @@ -5,7 +5,7 @@ DOCUMENTATION: short_description: Convert variable to JSON string description: - Converts an Ansible variable into a JSON string representation. - - This filter functions as a wrapper to the Python ``json.dumps()`` function. + - This filter functions as a wrapper to the Python C(json.dumps) function. - Ansible internally auto-converts JSON strings into variable structures so this plugin is used to force it into a JSON string. options: _input: @@ -13,18 +13,18 @@ DOCUMENTATION: type: raw required: true vault_to_text: - description: Toggle to either unvault a vault or create the JSON version of a vaulted object + description: Toggle to either unvault a vault or create the JSON version of a vaulted object. type: bool default: True version_added: '2.9' preprocess_unsafe: - description: Toggle to represent unsafe values directly in JSON or create a unsafe object in JSON + description: Toggle to represent unsafe values directly in JSON or create a unsafe object in JSON. type: bool default: True version_added: '2.9' allow_nan: - description: When off, strict adherence to float value limits of the JSON spec, so C(nan), C(inf) and C(-inf) values will produce errors - If on, JavaScript equivalents will be used (C(NaN), C(Infinity), C(-Infinity)) + description: When C(False), strict adherence to float value limits of the JSON specifications, so C(nan), C(inf) and C(-inf) values will produce errors. + When C(True), JavaScript equivalents will be used (C(NaN), C(Infinity), C(-Infinity)). default: True type: bool check_circular: @@ -32,29 +32,29 @@ DOCUMENTATION: default: True type: bool ensure_ascii: - description: Escapes all non ASCII characters + description: Escapes all non ASCII characters. default: True type: bool indent: - description: Number of spaces to indent python structures, mainly used for display to humans + description: Number of spaces to indent Python structures, mainly used for display to humans. default: 0 type: integer separators: description: The C(item) and C(key) separator to be used in the serialized output, - default may change depending on I(indent) and Python version + default may change depending on I(indent) and Python version. default: "(', ', ': ')" type: tuple skipkeys: - description: If C(True), keys that are not basic Python types will be skipped + description: If C(True), keys that are not basic Python types will be skipped. default: False type: bool sort_keys: - description: Affects sorting of dictionary keys + description: Affects sorting of dictionary keys. default: False type: bool notes: - - Both I(vault_to_text) and I(preprocess_unsafe) defaulted to C(False) between Ansible 2.9 and 2.12 - - 'These parameters to ``json.dumps()`` will be ignored, as they are overriden internally: I(cls), I(default)' + - Both I(vault_to_text) and I(preprocess_unsafe) defaulted to C(False) between Ansible 2.9 and 2.12. + - 'These parameters to C(json.dumps) will be ignored, as they are overriden internally: I(cls), I(default)' EXAMPLES: | # dump variable in a template to create a JSON document @@ -65,5 +65,5 @@ EXAMPLES: | RETURN: _value: - description: The JSON serialized string representing the variable structure inputted + description: The JSON serialized string representing the variable structure inputted. type: string diff --git a/lib/ansible/plugins/filter/to_nice_json.yml b/lib/ansible/plugins/filter/to_nice_json.yml index 8a804e91fc..bedc18bab5 100644 --- a/lib/ansible/plugins/filter/to_nice_json.yml +++ b/lib/ansible/plugins/filter/to_nice_json.yml @@ -5,26 +5,26 @@ DOCUMENTATION: short_description: Convert variable to 'nicely formatted' JSON string description: - Converts an Ansible variable into a 'nicely formatted' JSON string representation - - This filter functions as a wrapper to the Python ``json.dumps()`` function - - Ansible internally auto-converts JSON strings into variable structures so this plugin is used to force it into a JSON string + - This filter functions as a wrapper to the Python C(json.dumps) function. + - Ansible automatically converts JSON strings into variable structures so this plugin is used to forcibly retain a JSON string. options: _input: - description: A variable or expression that returns a data structure + description: A variable or expression that returns a data structure. type: raw required: true vault_to_text: - description: Toggle to either unvault a vault or create the JSON version of a vaulted object + description: Toggle to either unvault a vault or create the JSON version of a vaulted object. type: bool default: True version_added: '2.9' preprocess_unsafe: - description: Toggle to represent unsafe values directly in JSON or create a unsafe object in JSON + description: Toggle to represent unsafe values directly in JSON or create a unsafe object in JSON. type: bool default: True version_added: '2.9' allow_nan: - description: When off, strict adherence to float value limits of the JSON spec, so C(nan), C(inf) and C(-inf) values will produce errors - If on, JavaScript equivalents will be used (C(NaN), C(Infinity), C(-Infinity)). + description: When C(False), strict adherence to float value limits of the JSON specification, so C(nan), C(inf) and C(-inf) values will produce errors. + When C(True), JavaScript equivalents will be used (C(NaN), C(Infinity), C(-Infinity)). default: True type: bool check_circular: @@ -32,7 +32,7 @@ DOCUMENTATION: default: True type: bool ensure_ascii: - description: Escapes all non ASCII characters + description: Escapes all non ASCII characters. default: True type: bool skipkeys: @@ -40,8 +40,8 @@ DOCUMENTATION: default: False type: bool notes: - - Both I(vault_to_text) and I(preprocess_unsafe) defaulted to C(False) between Ansible 2.9 and 2.12 - - 'These parameters to ``json.dumps()`` will be ignored, they are overriden for internal use: I(cls), I(default), I(indent), I(separators), I(sort_keys).' + - Both I(vault_to_text) and I(preprocess_unsafe) defaulted to C(False) between Ansible 2.9 and 2.12. + - 'These parameters to C(json.dumps) will be ignored, they are overriden for internal use: I(cls), I(default), I(indent), I(separators), I(sort_keys).' EXAMPLES: | # dump variable in a template to create a nicely formatted JSON document @@ -50,5 +50,5 @@ EXAMPLES: | RETURN: _value: - description: The 'nicely formatted' JSON serialized string representing the variable structure inputted + description: The 'nicely formatted' JSON serialized string representing the variable structure inputted. type: string diff --git a/lib/ansible/plugins/filter/to_nice_yaml.yml b/lib/ansible/plugins/filter/to_nice_yaml.yml index bafb5713f2..4677a86135 100644 --- a/lib/ansible/plugins/filter/to_nice_yaml.yml +++ b/lib/ansible/plugins/filter/to_nice_yaml.yml @@ -5,7 +5,7 @@ DOCUMENTATION: short_description: Convert variable to YAML string description: - Converts an Ansible variable into a YAML string representation. - - This filter functions as a wrapper to the Python pyaml library's ``yaml.dump()`` function. + - This filter functions as a wrapper to the L(Python PyYAML library, https://pypi.org/project/PyYAML/)'s C(yaml.dump) function. - Ansible internally auto-converts YAML strings into variable structures so this plugin is used to force it into a YAML string. positional: _input options: @@ -14,10 +14,10 @@ DOCUMENTATION: type: raw required: true indent: - description: Number of spaces to indent python structures, mainly used for display to humans + description: Number of spaces to indent Python structures, mainly used for display to humans. type: integer sort_keys: - description: Affects sorting of dictionary keys + description: Affects sorting of dictionary keys. default: True type: bool #allow_unicode: @@ -26,14 +26,14 @@ DOCUMENTATION: # default: true #default_style=None, canonical=None, width=None, line_break=None, encoding=None, explicit_start=None, explicit_end=None, version=None, tags=None notes: - - more optoins may be available, see pyyaml docs for details - - 'These parameters to ``yaml.dump()`` will be ignored, as they are overriden internally: I(default_flow_style)' + - More options may be available, see L(PyYAML documentation, https://pyyaml.org/wiki/PyYAMLDocumentation) for details. + - 'These parameters to C(yaml.dump) will be ignored, as they are overriden internally: I(default_flow_style)' EXAMPLES: | # dump variable in a template to create a YAML document - {{ github_workflow |to_nice_yaml}} + {{ github_workflow | to_nice_yaml }} RETURN: _value: - description: The YAML serialized string representing the variable structure inputted + description: The YAML serialized string representing the variable structure inputted. type: string diff --git a/lib/ansible/plugins/filter/to_uuid.yml b/lib/ansible/plugins/filter/to_uuid.yml index 1c008e282d..266bf05fca 100644 --- a/lib/ansible/plugins/filter/to_uuid.yml +++ b/lib/ansible/plugins/filter/to_uuid.yml @@ -3,15 +3,15 @@ DOCUMENTATION: version_added: "2.9" short_description: namespaced UUID generator description: - - Use to generate namespeced Universal Unique ID + - Use to generate namespeced Universal Unique ID. positional: _input, namespace options: _input: - description: string to use as base fo the UUID + description: String to use as base fo the UUID. type: str required: true namespace: - description: UUID nsamespace to use + description: UUID namespace to use. type: str default: 361E6D51-FAEC-444A-9079-341386DA8E2E @@ -26,5 +26,5 @@ EXAMPLES: | RETURN: _value: - description: generated UUID + description: Generated UUID. type: string diff --git a/lib/ansible/plugins/filter/to_yaml.yml b/lib/ansible/plugins/filter/to_yaml.yml index f674b6e252..2e7be604a8 100644 --- a/lib/ansible/plugins/filter/to_yaml.yml +++ b/lib/ansible/plugins/filter/to_yaml.yml @@ -5,8 +5,8 @@ DOCUMENTATION: short_description: Convert variable to YAML string description: - Converts an Ansible variable into a YAML string representation. - - This filter functions as a wrapper to the Python pyaml library's ``yaml.dump()`` function. - - Ansible internally auto-converts YAML strings into variable structures so this plugin is used to force it into a YAML string. + - This filter functions as a wrapper to the L(Python PyYAML library, https://pypi.org/project/PyYAML/)'s C(yaml.dump) function. + - Ansible automatically converts YAML strings into variable structures so this plugin is used to forcibly retain a YAML string. positional: _input options: _input: @@ -14,14 +14,14 @@ DOCUMENTATION: type: raw required: true indent: - description: Number of spaces to indent python structures, mainly used for display to humans + description: Number of spaces to indent Python structures, mainly used for display to humans. type: integer sort_keys: - description: Affects sorting of dictionary keys + description: Affects sorting of dictionary keys. default: True type: bool notes: - - more optoins may be available, see pyyaml docs for details + - More options may be available, see L(PyYAML documentation, https://pyyaml.org/wiki/PyYAMLDocumentation) for details. # TODO: find docs for these #allow_unicode: @@ -48,5 +48,5 @@ EXAMPLES: | RETURN: _value: - description: The YAML serialized string representing the variable structure inputted + description: The YAML serialized string representing the variable structure inputted. type: string diff --git a/lib/ansible/plugins/filter/type_debug.yml b/lib/ansible/plugins/filter/type_debug.yml index 8ca941f7d9..73f79466b6 100644 --- a/lib/ansible/plugins/filter/type_debug.yml +++ b/lib/ansible/plugins/filter/type_debug.yml @@ -4,7 +4,7 @@ DOCUMENTATION: version_added: "2.3" short_description: show input data type description: - - Returns the equivalent of Python's ``type()`` function + - Returns the equivalent of Python's C(type) function. options: _input: description: Variable or expression of which you want to determine type. diff --git a/lib/ansible/plugins/filter/union.yml b/lib/ansible/plugins/filter/union.yml index 504a7e5733..d7379002b8 100644 --- a/lib/ansible/plugins/filter/union.yml +++ b/lib/ansible/plugins/filter/union.yml @@ -4,14 +4,14 @@ DOCUMENTATION: version_added: "1.4" short_description: union of lists description: - - Provide a unique list of all the elements of 2 lists. + - Provide a unique list of all the elements of two lists. options: _input: - description: A list + description: A list. type: list required: true _second_list: - description: A list + description: A list. type: list required: true seealso: @@ -31,5 +31,5 @@ EXAMPLES: | # => [1, 2, 5, 1, 3, 4, 10, 11, 99] RETURN: _value: - description: A unique list of all the elements from both lists + description: A unique list of all the elements from both lists. type: list diff --git a/lib/ansible/plugins/filter/unique.yml b/lib/ansible/plugins/filter/unique.yml index 15ec51f6fa..c627816b2e 100644 --- a/lib/ansible/plugins/filter/unique.yml +++ b/lib/ansible/plugins/filter/unique.yml @@ -7,7 +7,7 @@ DOCUMENTATION: - Creates a list of unique elements (a set) from the provided input list. options: _input: - description: A list + description: A list. type: list required: true seealso: @@ -26,5 +26,5 @@ EXAMPLES: | # => [1, 2, 5, 3, 4, 10] RETURN: _value: - description: A list with unique elements, also known as a set + description: A list with unique elements, also known as a set. type: list diff --git a/lib/ansible/plugins/filter/unvault.yml b/lib/ansible/plugins/filter/unvault.yml index 98e62a0b27..96a82ca8f7 100644 --- a/lib/ansible/plugins/filter/unvault.yml +++ b/lib/ansible/plugins/filter/unvault.yml @@ -4,7 +4,7 @@ DOCUMENTATION: version_added: "2.12" short_description: Open an Ansible Vault description: - - Retrieve your information from an encrypted Ansible Vault + - Retrieve your information from an encrypted Ansible Vault. positional: secret options: _input: @@ -12,11 +12,11 @@ DOCUMENTATION: type: string required: true secret: - description: Vault secret, the key that lets you open the vault + description: Vault secret, the key that lets you open the vault. type: string required: true vault_id: - description: Secret identifier, used internally to try to best match a secret when multiple are provided + description: Secret identifier, used internally to try to best match a secret when multiple are provided. type: string default: 'filter_default' diff --git a/lib/ansible/plugins/filter/urldecode.yml b/lib/ansible/plugins/filter/urldecode.yml index f63b3709b1..dd76937b6e 100644 --- a/lib/ansible/plugins/filter/urldecode.yml +++ b/lib/ansible/plugins/filter/urldecode.yml @@ -3,22 +3,24 @@ DOCUMENTATION: version_added: "2.4" short_description: get components from URL description: - - Given an URL, spiti it into it's component parts + - Split a URL into its component parts. positional: _input, query options: _input: - description: url string to split + description: URL string to split. type: str required: true query: - description: specify a single compoenent to return + description: Specify a single component to return. type: str choices: ["fragment", "hostname", "netloc", "password", "path", "port", "query", "scheme", "username"] RETURN: _value: - description: a dictionary with components as keyword and their value - type: dict + description: + - A dictionary with components as keyword and their value. + - If I(query) is provided, a string or integer will be returned instead, depending on I(query). + type: any EXAMPLES: | diff --git a/lib/ansible/plugins/filter/urlsplit.py b/lib/ansible/plugins/filter/urlsplit.py index 6e7588bc97..cce54bbbda 100644 --- a/lib/ansible/plugins/filter/urlsplit.py +++ b/lib/ansible/plugins/filter/urlsplit.py @@ -10,15 +10,15 @@ DOCUMENTATION = r''' version_added: "2.4" short_description: get components from URL description: - - Given an URL, spiti it into it's component parts + - Split a URL into its component parts. positional: _input, query options: _input: - description: url string to split + description: URL string to split. type: str required: true query: - description: specify a single compoenent to return + description: Specify a single component to return. type: str choices: ["fragment", "hostname", "netloc", "password", "path", "port", "query", "scheme", "username"] ''' @@ -51,8 +51,10 @@ EXAMPLES = r''' RETURN = r''' _value: - description: a dictionary with components as keyword and their value - type: dict + description: + - A dictionary with components as keyword and their value. + - If I(query) is provided, a string or integer will be returned instead, depending on I(query). + type: any ''' from urllib.parse import urlsplit diff --git a/lib/ansible/plugins/filter/vault.yml b/lib/ansible/plugins/filter/vault.yml index 721846c871..1ad541e9d4 100644 --- a/lib/ansible/plugins/filter/vault.yml +++ b/lib/ansible/plugins/filter/vault.yml @@ -4,29 +4,29 @@ DOCUMENTATION: version_added: "2.12" short_description: vault your secrets description: - - Put your information into an encrypted Ansible Vault + - Put your information into an encrypted Ansible Vault. positional: secret options: _input: - description: data to vault + description: Data to vault. type: string required: true secret: - description: Vault secret, the key that lets you open the vault + description: Vault secret, the key that lets you open the vault. type: string required: true salt: description: - - Encryption salt, will be random if not provided - - While providing one makes the resulting encrypted string reproducible, it can lower the security of the vault + - Encryption salt, will be random if not provided. + - While providing one makes the resulting encrypted string reproducible, it can lower the security of the vault. type: string vault_id: - description: Secret identifier, used internally to try to best match a secret when multiple are provided + description: Secret identifier, used internally to try to best match a secret when multiple are provided. type: string default: 'filter_default' wrap_object: description: - - This toggle can force the return of an C(AnsibleVaultEncryptedUnicode) string object, when C(False), you get a simple string + - This toggle can force the return of an C(AnsibleVaultEncryptedUnicode) string object, when C(False), you get a simple string. - Mostly useful when combining with the C(to_yaml) filter to output the 'inline vault' format. type: bool default: False @@ -44,5 +44,5 @@ EXAMPLES: | RETURN: _value: - description: The vault string that contains the secret data (or AnsibleVaultEncryptedUnicode string object) + description: The vault string that contains the secret data (or C(AnsibleVaultEncryptedUnicode) string object). type: string diff --git a/lib/ansible/plugins/filter/zip.yml b/lib/ansible/plugins/filter/zip.yml index f0f875cdcf..20d7a9b9a0 100644 --- a/lib/ansible/plugins/filter/zip.yml +++ b/lib/ansible/plugins/filter/zip.yml @@ -3,22 +3,22 @@ DOCUMENTATION: version_added: "2.3" short_description: combine list elements positional: _input, _additional_lists - description: Iterate over several iterables in parallel, producing tuples with an item from each one + description: Iterate over several iterables in parallel, producing tuples with an item from each one. notes: - - This is mostly a passhtrough to Python's C(zip) function + - This is mostly a passhtrough to Python's C(zip) function. options: _input: - description: Original list + description: Original list. type: list elements: any required: yes _additional_lists: - description: Additional list(s) + description: Additional list(s). type: list elements: any required: yes strict: - description: If C(True) return an error on mismatching list length, otherwise shortest list determines output + description: If C(True) return an error on mismatching list length, otherwise shortest list determines output. type: bool default: no @@ -38,6 +38,6 @@ EXAMPLES: | RETURN: _value: - description: list of lists made of elements matching the positions of the input lists + description: List of lists made of elements matching the positions of the input lists. type: list elements: list diff --git a/lib/ansible/plugins/filter/zip_longest.yml b/lib/ansible/plugins/filter/zip_longest.yml index be25d8332d..db351b4014 100644 --- a/lib/ansible/plugins/filter/zip_longest.yml +++ b/lib/ansible/plugins/filter/zip_longest.yml @@ -5,23 +5,23 @@ DOCUMENTATION: positional: _input, _additional_lists description: - Make an iterator that aggregates elements from each of the iterables. - If the iterables are of uneven length, missing values are filled-in with fillvalue. + If the iterables are of uneven length, missing values are filled-in with I(fillvalue). Iteration continues until the longest iterable is exhausted. notes: - This is mostly a passhtrough to Python's C(itertools.zip_longest) function options: _input: - description: Original list + description: Original list. type: list elements: any required: yes _additional_lists: - description: Additional list(s) + description: Additional list(s). type: list elements: any required: yes fillvalue: - description: Filler value to add to output when one of the lists does not contain enough elements to match the others + description: Filler value to add to output when one of the lists does not contain enough elements to match the others. type: any EXAMPLES: | @@ -31,6 +31,6 @@ EXAMPLES: | RETURN: _value: - description: list of lists made of elements matching the positions of the input lists + description: List of lists made of elements matching the positions of the input lists. type: list elements: list |