ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-08-02 20:24:23 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Generate many Ansible outputs with 'antsibull-docs ansible-output'.

Browse source
This commit is contained in:
Felix Fontein 2025-07-16 15:28:10 +02:00
commit e194a38061
10 changed files with 216 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

5
docs/docsite/config.yml
View file

@ -5,3 +5,8 @@
changelog:
write_changelog: true
ansible_output:
global_env:
ANSIBLE_STDOUT_CALLBACK: community.general.tasks_only
ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS: 90

24
docs/docsite/rst/filter_guide_abstract_informations_counting_elements_in_sequence.rst
View file

@ -20,6 +20,17 @@ The :ansplugin:`community.general.counter filter plugin <community.general.count
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Count character occurrences in a string] ********************************************
@ -72,9 +83,20 @@ This plugin is useful for selecting resources based on current allocation:
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Get ID of SCSI controller(s) with less than 4 disks attached and choose the one with the least disks]
TASK [Get ID of SCSI controller(s) with less than 4 disks attached and choose the one with the least disks] ***
ok: [localhost] => {
"msg": "scsi_2"
}

32
docs/docsite/rst/filter_guide_abstract_informations_dictionaries.rst
View file

@ -31,16 +31,27 @@ You can use the :ansplugin:`community.general.dict_kv filter <community.general.
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Create a single-entry dictionary] **************************************************
TASK [Create a single-entry dictionary] ***************************************************
ok: [localhost] => {
"msg": {
"thatsmyvar": "myvalue"
}
}
TASK [Create a list of dictionaries where the 'server' field is taken from a list] *******
TASK [Create a list of dictionaries where the 'server' field is taken from a list] ********
ok: [localhost] => {
"msg": [
{
@ -87,9 +98,20 @@ If you need to convert a list of key-value pairs to a dictionary, you can use th
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Create a dictionary with the dict function] ****************************************
TASK [Create a dictionary with the dict function] *****************************************
ok: [localhost] => {
"msg": {
"1": 2,
@ -97,7 +119,7 @@ This produces:
}
}
TASK [Create a dictionary with the community.general.dict filter] ************************
TASK [Create a dictionary with the community.general.dict filter] *************************
ok: [localhost] => {
"msg": {
"1": 2,
@ -105,7 +127,7 @@ This produces:
}
}
TASK [Create a list of dictionaries with map and the community.general.dict filter] ******
TASK [Create a list of dictionaries with map and the community.general.dict filter] *******
ok: [localhost] => {
"msg": [
{

45
docs/docsite/rst/filter_guide_abstract_informations_grouping.rst
View file

@ -22,6 +22,49 @@ One example is ``ansible_facts.mounts``, which is a list of dictionaries where e
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
skip_first_lines: 3 # the set_fact task
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- ansible.builtin.set_fact:
ansible_facts:
mounts:
- block_available: 2000
block_size: 4096
block_total: 2345
block_used: 345
device: "/dev/sda1"
fstype: "ext4"
inode_available: 500
inode_total: 512
inode_used: 12
mount: "/boot"
options: "rw,relatime,data=ordered"
size_available: 56821
size_total: 543210
uuid: "ab31cade-d9c1-484d-8482-8a4cbee5241a"
- block_available: 1234
block_size: 4096
block_total: 12345
block_used: 11111
device: "/dev/sda2"
fstype: "ext4"
inode_available: 1111
inode_total: 1234
inode_used: 123
mount: "/"
options: "rw,relatime"
size_available: 42143
size_total: 543210
uuid: "abcdef01-2345-6789-0abc-def012345678"
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Output mount facts grouped by device name] ******************************************
@ -79,7 +122,7 @@ This produces:
"options": "rw,relatime",
"size_available": 42143,
"size_total": 543210,
"uuid": "bdf50b7d-4859-40af-8665-c637ee7a7808"
"uuid": "abcdef01-2345-6789-0abc-def012345678"
},
"/boot": {
"block_available": 2000,

39
docs/docsite/rst/filter_guide_conversions.rst
View file

@ -24,6 +24,17 @@ Ansible offers the :ansplugin:`community.general.read_csv module <community.gene
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Parse CSV from string] **************************************************************
@ -69,6 +80,34 @@ Converting to JSON
This produces:
.. ansible-output-data::
skip_first_lines: 3
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- ansible.builtin.set_fact:
result_stdout: |-
bin
boot
dev
etc
home
lib
proc
root
run
tmp
- name: Run 'ls' to list files in /
command: ls /
register: result
- name: Parse the ls output
debug:
msg: "{{ result_stdout | community.general.jc('ls') }}"
.. code-block:: ansible-output
TASK [Run 'ls' to list files in /] ********************************************************

31
docs/docsite/rst/filter_guide_creating_identifiers.rst
View file

@ -25,6 +25,17 @@ Hashids
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Create hashid] **********************************************************************
@ -66,16 +77,32 @@ You can use the :ansplugin:`community.general.random_mac filter <community.gener
This produces:
.. ansible-output-data::
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- name: "Create a random MAC starting with ff:"
debug:
# We're using a seed here to avoid randomness in the output
msg: "{{ 'FF' | community.general.random_mac(seed='') }}"
- name: "Create a random MAC starting with 00:11:22:"
debug:
# We're using a seed here to avoid randomness in the output
msg: "{{ '00:11:22' | community.general.random_mac(seed='') }}"
.. code-block:: ansible-output
TASK [Create a random MAC starting with ff:] **********************************************
ok: [localhost] => {
"msg": "ff:69:d3:78:7f:b4"
"msg": "ff:84:f5:d1:59:20"
}
TASK [Create a random MAC starting with 00:11:22:] ****************************************
ok: [localhost] => {
"msg": "00:11:22:71:5d:3b"
"msg": "00:11:22:84:f5:d1"
}
You can also initialize the random number generator from a seed to create random-but-idempotent MAC addresses:

17
docs/docsite/rst/filter_guide_working_with_times.rst
View file

@ -69,21 +69,32 @@ Note that months and years are using a simplified representation: a month is 30
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Convert string to seconds] **********************************************************
ok: [localhost] => {
"msg": "109210.123"
"msg": 109210.123
}
TASK [Convert string to hours] ************************************************************
ok: [localhost] => {
"msg": "30.336145277778"
"msg": 30.336145277778
}
TASK [Convert string to years (using 365.25 days == 1 year)] ******************************
ok: [localhost] => {
"msg": "1.096851471595"
"msg": 1.096851471595
}
.. versionadded: 0.2.0

13
docs/docsite/rst/filter_guide_working_with_unicode.rst
View file

@ -21,9 +21,20 @@ You can use the :ansplugin:`community.general.unicode_normalize filter <communit
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Compare Unicode representations] ********************************************************
TASK [Compare Unicode representations] ****************************************************
ok: [localhost] => {
"msg": true
}

11
docs/docsite/rst/filter_guide_working_with_versions.rst
View file

@ -23,6 +23,17 @@ If you need to sort a list of version numbers, the Jinja ``sort`` filter is prob
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Sort list by version number] ********************************************************

12
noxfile.py
View file

@ -32,6 +32,18 @@ def botmeta(session: nox.Session) -> None:
session.run("python", "tests/sanity/extra/botmeta.py")
@nox.session(name="ansible-output", default=False)
def ansible_output(session: nox.Session) -> None:
session.install(
"ansible-core",
"antsibull-docs",
# Needed libs for some code blocks:
"jc",
"hashids",
)
session.run("antsibull-docs", "ansible-output", *session.posargs)
# Allow to run the noxfile with `python noxfile.py`, `pipx run noxfile.py`, or similar.
# Requires nox >= 2025.02.09
if __name__ == "__main__":