Skip to content

Commit edc7392

Browse files
felixfonteinfelixfontein
authored
Allow to specify and render role attributes (#103)
* Allow to specify and render role attributes. * Add role test.
1 parent d4c2e9f commit edc7392

File tree

20 files changed

+1435
-0
lines changed

20 files changed

+1435
-0
lines changed

‎changelogs/fragments/103-roles-schema.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
minor_changes:
2+
- "Update schema for roles argument spec to allow specifying attributes on the entrypoint level. These are now also rendered when present (https://github.com/ansible-community/antsibull-docs/pull/103)."

‎src/antsibull_docs/data/docsite/role.rst.j2

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
SPDX-License-Identifier: GPL-3.0-or-later
55
#}
66

7+
{% from 'macros/attributes.rst.j2' import in_rst as attributes_rst with context %}
78
{% from 'macros/parameters.rst.j2' import in_rst as parameters_rst with context %}
89
{% from 'macros/parameters.rst.j2' import in_html as parameters_html with context %}
910
{% from 'macros/version_added.rst.j2' import version_added_rst %}
@@ -14,6 +15,12 @@
1415
:github_url: @{ edit_on_github_url }@?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr
1516
{% endif %}
1617

18+
.. role:: ansible-attribute-support-label
19+
.. role:: ansible-attribute-support-property
20+
.. role:: ansible-attribute-support-full
21+
.. role:: ansible-attribute-support-partial
22+
.. role:: ansible-attribute-support-none
23+
.. role:: ansible-attribute-support-na
1724
.. role:: ansible-option-type
1825
.. role:: ansible-option-elements
1926
.. role:: ansible-option-required
@@ -148,6 +155,16 @@ Parameters
148155
{% endif %}
149156
{% endif %}
150157

158+
.. Attributes
159+
160+
{% if ep_doc['attributes'] %}
161+
162+
Attributes
163+
----------
164+
165+
@{ attributes_rst(ep_doc['attributes']) }@
166+
{% endif %}
167+
151168
.. Notes
152169

153170
{% if ep_doc['notes'] -%}

‎src/antsibull_docs/schemas/docs/role.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@
1616

1717
from .base import (
1818
COLLECTION_NAME_F,
19+
AttributeSchema,
20+
AttributeSchemaActionGroup,
21+
AttributeSchemaPlatform,
1922
BaseModel,
2023
DeprecationSchema,
2124
OptionsSchema,
@@ -55,6 +58,9 @@ class RoleEntrypointSchema(BaseModel):
5558
seealso: t.List[t.Union[SeeAlsoModSchema, SeeAlsoRefSchema, SeeAlsoLinkSchema]] = []
5659
todo: t.List[str] = []
5760
version_added: str = 'historical'
61+
attributes: t.Dict[str, t.Union[AttributeSchema,
62+
AttributeSchemaActionGroup,
63+
AttributeSchemaPlatform]] = {}
5864

5965
options: t.Dict[str, RoleOptionsSchema] = {}
6066

‎tests/functional/baseline-default/collections/index_role.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
2+
:orphan:
3+
4+
.. _list_of_role_plugins:
5+
6+
Index of all Roles
7+
==================
8+
9+
ns2.col
10+
-------
11+
12+
* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_role>` -- Foo role
13+

‎tests/functional/baseline-default/collections/ns2/col/foo_role.rst

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
2+
.. Document meta
3+
4+
:orphan:
5+
:github_url: https://github.com/ansible-community/antsibull-docs/edit/main/tests/functional/collections/ansible_collections/ns2/col/roles/foo/meta/argument_specs.yml?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr
6+
7+
.. role:: ansible-attribute-support-label
8+
.. role:: ansible-attribute-support-property
9+
.. role:: ansible-attribute-support-full
10+
.. role:: ansible-attribute-support-partial
11+
.. role:: ansible-attribute-support-none
12+
.. role:: ansible-attribute-support-na
13+
.. role:: ansible-option-type
14+
.. role:: ansible-option-elements
15+
.. role:: ansible-option-required
16+
.. role:: ansible-option-versionadded
17+
.. role:: ansible-option-aliases
18+
.. role:: ansible-option-choices
19+
.. role:: ansible-option-choices-default-mark
20+
.. role:: ansible-option-default-bold
21+
22+
.. Anchors
23+
24+
.. _ansible_collections.ns2.col.foo_role:
25+
26+
.. Anchors: aliases
27+
28+
29+
.. Title
30+
31+
ns2.col.foo role -- Foo role
32+
++++++++++++++++++++++++++++
33+
34+
.. Collection note
35+
36+
.. note::
37+
This role is part of the `ns2.col collection <https://galaxy.ansible.com/ns2/col>`_ (version 2.1.0).
38+
39+
To install it use: :code:`ansible-galaxy collection install ns2.col`.
40+
41+
To use it in a playbook, specify: :code:`ns2.col.foo`.
42+
43+
.. contents::
44+
:local:
45+
:depth: 2
46+
47+
48+
.. Entry point title
49+
50+
Entry point ``main`` -- Foo role
51+
--------------------------------
52+
53+
.. version_added
54+
55+
.. rst-class:: ansible-version-added
56+
57+
New in ns2.col 0.2.0
58+
59+
.. Deprecated
60+
61+
62+
Synopsis
63+
^^^^^^^^
64+
65+
.. Description
66+
67+
- This is the foo role.
68+
69+
.. Requirements
70+
71+
72+
.. Options
73+
74+
Parameters
75+
^^^^^^^^^^
76+
77+
.. rst-class:: ansible-option-table
78+
79+
.. list-table::
80+
:width: 100%
81+
:widths: auto
82+
:header-rows: 1
83+
84+
* - Parameter
85+
- Comments
86+
87+
* - .. raw:: html
88+
89+
<div class="ansible-option-cell">
90+
<div class="ansibleOptionAnchor" id="parameter-main--foo_param_1"></div>
91+
92+
.. _ansible_collections.ns2.col.foo_role__parameter-main__foo_param_1:
93+
94+
.. rst-class:: ansible-option-title
95+
96+
**foo_param_1**
97+
98+
.. raw:: html
99+
100+
<a class="ansibleOptionLink" href="#parameter-main--foo_param_1" title="Permalink to this option"></a>
101+
102+
.. rst-class:: ansible-option-type-line
103+
104+
:ansible-option-type:`string`
105+
106+
107+
108+
109+
.. raw:: html
110+
111+
</div>
112+
113+
- .. raw:: html
114+
115+
<div class="ansible-option-cell">
116+
117+
A string parameter
118+
119+
120+
.. raw:: html
121+
122+
</div>
123+
124+
* - .. raw:: html
125+
126+
<div class="ansible-option-cell">
127+
<div class="ansibleOptionAnchor" id="parameter-main--foo_param_2"></div>
128+
129+
.. _ansible_collections.ns2.col.foo_role__parameter-main__foo_param_2:
130+
131+
.. rst-class:: ansible-option-title
132+
133+
**foo_param_2**
134+
135+
.. raw:: html
136+
137+
<a class="ansibleOptionLink" href="#parameter-main--foo_param_2" title="Permalink to this option"></a>
138+
139+
.. rst-class:: ansible-option-type-line
140+
141+
:ansible-option-type:`integer`
142+
143+
144+
145+
146+
.. raw:: html
147+
148+
</div>
149+
150+
- .. raw:: html
151+
152+
<div class="ansible-option-cell">
153+
154+
An integer parameter with a default.
155+
156+
157+
.. rst-class:: ansible-option-line
158+
159+
:ansible-option-default-bold:`Default:` :ansible-option-default:`13`
160+
161+
.. raw:: html
162+
163+
</div>
164+
165+
166+
.. Attributes
167+
168+
169+
Attributes
170+
----------
171+
172+
.. rst-class:: ansible-option-table
173+
174+
.. list-table::
175+
:width: 100%
176+
:widths: auto
177+
:header-rows: 1
178+
179+
* - Attribute
180+
- Support
181+
- Description
182+
183+
* - .. raw:: html
184+
185+
<div class="ansible-option-cell">
186+
<div class="ansibleOptionAnchor" id="attribute-check_mode"></div>
187+
188+
.. _ansible_collections.ns2.col.foo_role__attribute-check_mode:
189+
190+
.. rst-class:: ansible-option-title
191+
192+
**check_mode**
193+
194+
.. raw:: html
195+
196+
<a class="ansibleOptionLink" href="#attribute-check_mode" title="Permalink to this attribute"></a>
197+
198+
.. raw:: html
199+
200+
</div>
201+
202+
- .. raw:: html
203+
204+
<div class="ansible-option-cell">
205+
206+
:ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full`
207+
208+
209+
.. raw:: html
210+
211+
</div>
212+
213+
- .. raw:: html
214+
215+
<div class="ansible-option-cell">
216+
217+
Can run in check\_mode and return changed status prediction without modifying target
218+
219+
220+
.. raw:: html
221+
222+
</div>
223+
224+
225+
226+
.. Notes
227+
228+
229+
.. Seealso
230+
231+
See Also
232+
^^^^^^^^
233+
234+
.. seealso::
235+
236+
\ :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_module>`\
237+
The official documentation on the **ns2.col.foo** module.
238+
239+
Authors
240+
^^^^^^^
241+
242+
- Felix Fontein (@felixfontein)
243+
244+
245+
246+
.. Extra links
247+
248+
Collection links
249+
~~~~~~~~~~~~~~~~
250+
251+
.. raw:: html
252+
253+
<p class="ansible-links">
254+
<a href="https://github.com/ansible-collections/community.general/issues" aria-role="button" target="_blank" rel="noopener external">Issue Tracker</a>
255+
<a href="https://github.com/ansible-collections/community.crypto" aria-role="button" target="_blank" rel="noopener external">Homepage</a>
256+
<a href="https://github.com/ansible-collections/community.internal_test_tools" aria-role="button" target="_blank" rel="noopener external">Repository (Sources)</a>
257+
<a href="https://github.com/ansible-community/antsibull-docs/issues/new?assignees=&amp;labels=&amp;template=bug_report.md" aria-role="button" target="_blank" rel="noopener external">Submit a bug report</a>
258+
<a href="./#communication-for-ns2-col" aria-role="button" target="_blank">Communication</a>
259+
</p>
260+
261+
.. Parsing errors
262+

‎tests/functional/baseline-default/collections/ns2/col/index.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,19 @@ Vars Plugins
229229
foo_vars
230230

231231

232+
Role Index
233+
----------
234+
235+
These are the roles in the ns2.col collection:
236+
237+
* :ref:`foo role <ansible_collections.ns2.col.foo_role>` -- Foo role
238+
239+
.. toctree::
240+
:maxdepth: 1
241+
:hidden:
242+
243+
foo_role
244+
232245

233246
.. seealso::
234247

‎tests/functional/baseline-no-breadcrumbs/collections/index_role.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
2+
:orphan:
3+
4+
.. _list_of_role_plugins:
5+
6+
Index of all Roles
7+
==================
8+
9+
ns2.col
10+
-------
11+
12+
* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_role>` -- Foo role
13+

0 commit comments

Comments
 (0)