Skip to content

Commit 1c04218

Browse files
felixfonteinfelixfontein
authored
Extra docs: generate Ansible outputs with 'antsibull-docs ansible-output' (#10421)
* Generate many Ansible outputs with 'antsibull-docs ansible-output'. * Generate YAML output as well. * Check ansible-output from CI instead of updating. * Use reset-previous-blocks meta action; generate more code blocks. * Use set-template meta action. * Run ansible-output in CI if anything in docs/ is changed. * Remove unnecessary allow_duplicate_keys.
1 parent 38d1b47 commit 1c04218

17 files changed

+740
-66
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
# Copyright (c) Ansible Project
3+
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
4+
# SPDX-License-Identifier: GPL-3.0-or-later
5+
6+
name: nox
7+
'on':
8+
push:
9+
branches:
10+
- main
11+
- stable-*
12+
paths:
13+
- docs/**
14+
pull_request:
15+
paths:
16+
- docs/**
17+
# Run CI once per day (at 08:00 UTC)
18+
schedule:
19+
- cron: '0 8 * * *'
20+
workflow_dispatch:
21+
22+
jobs:
23+
nox:
24+
runs-on: ubuntu-latest
25+
name: "Validate generated Ansible output"
26+
steps:
27+
- name: Check out collection
28+
uses: actions/checkout@v5
29+
with:
30+
persist-credentials: false
31+
- name: Run nox
32+
uses: ansible-community/antsibull-nox@main
33+
with:
34+
sessions: ansible-output

‎docs/docsite/config.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,13 @@
55

66
changelog:
77
write_changelog: true
8+
9+
ansible_output:
10+
global_env:
11+
ANSIBLE_STDOUT_CALLBACK: community.general.tasks_only
12+
ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS: 90
13+
global_postprocessors:
14+
reformat-yaml:
15+
command:
16+
- python
17+
- docs/docsite/reformat-yaml.py

‎docs/docsite/reformat-yaml.py‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
#!/usr/bin/env python
2+
# Copyright (c) Ansible Project
3+
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
4+
# SPDX-License-Identifier: GPL-3.0-or-later
5+
6+
import sys
7+
from io import StringIO
8+
9+
from ruamel.yaml import YAML
10+
11+
12+
def main() -> None:
13+
yaml = YAML(typ='rt')
14+
yaml.indent(mapping=2, sequence=4, offset=2)
15+
16+
# Load
17+
data = yaml.load(sys.stdin)
18+
19+
# Dump
20+
sio = StringIO()
21+
yaml.dump(data, sio)
22+
print(sio.getvalue().rstrip('\n'))
23+
24+
25+
if __name__ == "__main__":
26+
main()

‎docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst‎

Lines changed: 74 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,34 @@ Use the filter :ansplugin:`community.general.keep_keys#filter` if you have a lis
1313

1414
Let us use the below list in the following examples:
1515

16+
.. ansible-output-meta::
17+
18+
actions:
19+
- name: reset-previous-blocks
20+
- name: set-template
21+
template:
22+
env:
23+
ANSIBLE_CALLBACK_RESULT_FORMAT: yaml
24+
variables:
25+
data:
26+
previous_code_block: yaml
27+
previous_code_block_index: 0
28+
computation:
29+
previous_code_block: yaml+jinja
30+
postprocessors:
31+
- name: reformat-yaml
32+
language: yaml
33+
skip_first_lines: 2
34+
playbook: |-
35+
- hosts: localhost
36+
gather_facts: false
37+
tasks:
38+
- vars:
39+
@{{ data | indent(8) }}@
40+
@{{ computation | indent(8) }}@
41+
ansible.builtin.debug:
42+
var: result
43+
1644
.. code-block:: yaml
1745
1846
input:
@@ -37,24 +65,48 @@ Let us use the below list in the following examples:
3765

3866
gives
3967

68+
.. ansible-output-data::
69+
70+
playbook: ~
71+
4072
.. code-block:: yaml
4173
:emphasize-lines: 1-
4274
4375
result:
44-
- {k0_x0: A0, k1_x1: B0}
45-
- {k0_x0: A1, k1_x1: B1}
76+
- k0_x0: A0
77+
k1_x1: B0
78+
- k0_x0: A1
79+
k1_x1: B1
4680
4781
4882
.. versionadded:: 9.1.0
4983

5084
* The results of the below examples 1-5 are all the same:
5185

86+
.. ansible-output-data::
87+
88+
playbook: |-
89+
- hosts: localhost
90+
gather_facts: false
91+
tasks:
92+
- vars:
93+
@{{ data | indent(8) }}@
94+
95+
# I picked one of the examples
96+
mp: equal
97+
target: ['k0_x0', 'k1_x1']
98+
result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
99+
ansible.builtin.debug:
100+
var: result
101+
52102
.. code-block:: yaml
53103
:emphasize-lines: 1-
54104
55105
result:
56-
- {k0_x0: A0, k1_x1: B0}
57-
- {k0_x0: A1, k1_x1: B1}
106+
- k0_x0: A0
107+
k1_x1: B0
108+
- k0_x0: A1
109+
k1_x1: B1
58110
59111
60112
1. Match keys that equal any of the items in the target.
@@ -105,12 +157,28 @@ gives
105157

106158
* The results of the below examples 6-9 are all the same:
107159

160+
.. ansible-output-data::
161+
162+
playbook: |-
163+
- hosts: localhost
164+
gather_facts: false
165+
tasks:
166+
- vars:
167+
@{{ data | indent(8) }}@
168+
169+
# I picked one of the examples
170+
mp: equal
171+
target: k0_x0
172+
result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
173+
ansible.builtin.debug:
174+
var: result
175+
108176
.. code-block:: yaml
109177
:emphasize-lines: 1-
110178
111179
result:
112-
- {k0_x0: A0}
113-
- {k0_x0: A1}
180+
- k0_x0: A0
181+
- k0_x0: A1
114182
115183
116184
6. Match keys that equal the target.
@@ -148,4 +216,3 @@ gives
148216
mp: regex
149217
target: ^.*0_x.*$
150218
result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
151-

‎docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst‎

Lines changed: 76 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,34 @@ Use the filter :ansplugin:`community.general.remove_keys#filter` if you have a l
1313

1414
Let us use the below list in the following examples:
1515

16+
.. ansible-output-meta::
17+
18+
actions:
19+
- name: reset-previous-blocks
20+
- name: set-template
21+
template:
22+
env:
23+
ANSIBLE_CALLBACK_RESULT_FORMAT: yaml
24+
variables:
25+
data:
26+
previous_code_block: yaml
27+
previous_code_block_index: 0
28+
computation:
29+
previous_code_block: yaml+jinja
30+
postprocessors:
31+
- name: reformat-yaml
32+
language: yaml
33+
skip_first_lines: 2
34+
playbook: |-
35+
- hosts: localhost
36+
gather_facts: false
37+
tasks:
38+
- vars:
39+
@{{ data | indent(8) }}@
40+
@{{ computation | indent(8) }}@
41+
ansible.builtin.debug:
42+
var: result
43+
1644
.. code-block:: yaml
1745
1846
input:
@@ -37,27 +65,51 @@ Let us use the below list in the following examples:
3765

3866
gives
3967

68+
.. ansible-output-data::
69+
70+
playbook: ~
71+
4072
.. code-block:: yaml
4173
:emphasize-lines: 1-
4274
4375
result:
44-
- k2_x2: [C0]
76+
- k2_x2:
77+
- C0
4578
k3_x3: foo
46-
- k2_x2: [C1]
79+
- k2_x2:
80+
- C1
4781
k3_x3: bar
4882
4983
5084
.. versionadded:: 9.1.0
5185

5286
* The results of the below examples 1-5 are all the same:
5387

88+
.. ansible-output-data::
89+
90+
playbook: |-
91+
- hosts: localhost
92+
gather_facts: false
93+
tasks:
94+
- vars:
95+
@{{ data | indent(8) }}@
96+
97+
# I picked one of the examples
98+
mp: equal
99+
target: ['k0_x0', 'k1_x1']
100+
result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
101+
ansible.builtin.debug:
102+
var: result
103+
54104
.. code-block:: yaml
55105
:emphasize-lines: 1-
56106
57107
result:
58-
- k2_x2: [C0]
108+
- k2_x2:
109+
- C0
59110
k3_x3: foo
60-
- k2_x2: [C1]
111+
- k2_x2:
112+
- C1
61113
k3_x3: bar
62114
63115
@@ -109,15 +161,33 @@ gives
109161

110162
* The results of the below examples 6-9 are all the same:
111163

164+
.. ansible-output-data::
165+
166+
playbook: |-
167+
- hosts: localhost
168+
gather_facts: false
169+
tasks:
170+
- vars:
171+
@{{ data | indent(8) }}@
172+
173+
# I picked one of the examples
174+
mp: equal
175+
target: k0_x0
176+
result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
177+
ansible.builtin.debug:
178+
var: result
179+
112180
.. code-block:: yaml
113181
:emphasize-lines: 1-
114182
115183
result:
116184
- k1_x1: B0
117-
k2_x2: [C0]
185+
k2_x2:
186+
- C0
118187
k3_x3: foo
119188
- k1_x1: B1
120-
k2_x2: [C1]
189+
k2_x2:
190+
- C1
121191
k3_x3: bar
122192
123193
@@ -156,4 +226,3 @@ gives
156226
mp: regex
157227
target: ^.*0_x.*$
158228
result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
159-

0 commit comments

Comments
 (0)