From a1e2b935ef515d86ddad2252d5e6035a9d047a4b Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 10 Feb 2024 14:59:13 +0100 Subject: [PATCH 1/2] Support examples for role entrypoints. --- .../fragments/244-role-entrypoint-examples.yml | 2 ++ .../data/docsite/ansible-docsite/role.rst.j2 | 10 ++++++++++ .../data/docsite/simplified-rst/role.rst.j2 | 10 ++++++++++ src/antsibull_docs/schemas/docs/role.py | 1 + tests/functional/ansible-doc-cache-all-others.json | 2 ++ tests/functional/ansible-doc-cache-all.json | 2 ++ ...le-doc-cache-ansible.builtin-ns.col2-ns2.col.json | 2 ++ .../ansible-doc-cache-ansible.builtin-ns2.col.json | 1 + ...oc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json | 2 ++ ...nsible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json | 1 + tests/functional/ansible-doc-cache-ns.col2.json | 1 + tests/functional/ansible-doc-cache-ns2.col.json | 1 + .../collections/ns/col2/bar_role.rst | 9 +++++++++ .../collections/ns2/col/foo_role.rst | 12 ++++++++++++ .../collections/ns/col2/bar_role.rst | 9 +++++++++ .../collections/ns2/col/foo_role.rst | 12 ++++++++++++ .../collections/ns2/col/foo_role.rst | 12 ++++++++++++ .../foo_role.rst | 12 ++++++++++++ .../collections/ns/col2/bar_role.rst | 9 +++++++++ .../collections/ns2/col/foo_role.rst | 12 ++++++++++++ .../baseline-squash-hierarchy/foo_role.rst | 12 ++++++++++++ .../collections/ns2/col/foo_role.rst | 12 ++++++++++++ .../ns/col2/roles/bar/meta/argument_specs.yml | 1 + .../ns2/col/roles/foo/meta/argument_specs.yml | 6 ++++++ 24 files changed, 153 insertions(+) create mode 100644 changelogs/fragments/244-role-entrypoint-examples.yml diff --git a/changelogs/fragments/244-role-entrypoint-examples.yml b/changelogs/fragments/244-role-entrypoint-examples.yml new file mode 100644 index 00000000..afe93380 --- /dev/null +++ b/changelogs/fragments/244-role-entrypoint-examples.yml @@ -0,0 +1,2 @@ +minor_changes: + - "Support examples for role entrypoints (https://github.com/ansible-community/antsibull-docs/pull/244)." diff --git a/src/antsibull_docs/data/docsite/ansible-docsite/role.rst.j2 b/src/antsibull_docs/data/docsite/ansible-docsite/role.rst.j2 index 6761b028..421a0adc 100644 --- a/src/antsibull_docs/data/docsite/ansible-docsite/role.rst.j2 +++ b/src/antsibull_docs/data/docsite/ansible-docsite/role.rst.j2 @@ -189,6 +189,16 @@ See Also {% endfor %} {% endif %} +{% if ep_doc['examples'] -%} +Examples +-------- + +.. code-block:: yaml+jinja + +@{ ep_doc['examples'] | indent(4, True) }@ + +{% endif %} + {% if ep_doc['author'] -%} Authors ^^^^^^^ diff --git a/src/antsibull_docs/data/docsite/simplified-rst/role.rst.j2 b/src/antsibull_docs/data/docsite/simplified-rst/role.rst.j2 index 8f83fc36..2832b0f8 100644 --- a/src/antsibull_docs/data/docsite/simplified-rst/role.rst.j2 +++ b/src/antsibull_docs/data/docsite/simplified-rst/role.rst.j2 @@ -146,6 +146,16 @@ See Also {% endfor %} {% endif %} +{% if ep_doc['examples'] -%} +Examples +-------- + +.. code-block:: yaml + +@{ ep_doc['examples'] | indent(4, True) }@ + +{% endif %} + {% if ep_doc['author'] -%} Authors ^^^^^^^ diff --git a/src/antsibull_docs/schemas/docs/role.py b/src/antsibull_docs/schemas/docs/role.py index f4f72dc8..d62d893d 100644 --- a/src/antsibull_docs/schemas/docs/role.py +++ b/src/antsibull_docs/schemas/docs/role.py @@ -65,6 +65,7 @@ class RoleEntrypointSchema(BaseModel): str, t.Union[AttributeSchema, AttributeSchemaActionGroup, AttributeSchemaPlatform], ] = {} + examples: str = "" options: dict[str, RoleOptionsSchema] = {} diff --git a/tests/functional/ansible-doc-cache-all-others.json b/tests/functional/ansible-doc-cache-all-others.json index b7224d33..864f0920 100644 --- a/tests/functional/ansible-doc-cache-all-others.json +++ b/tests/functional/ansible-doc-cache-all-others.json @@ -23395,6 +23395,7 @@ "description": [ "This is the baz entrypoint of the bar role." ], + "examples": "An example.", "short_description": "Bar role, baz entrypoint \u30c6\u30b9\u30c8\u30ed\u30fc\u30eb" }, "main": { @@ -23448,6 +23449,7 @@ "This is the foo role.", "If you set O(foo_param_1) while O(foo_param_2=3), this might behave funny." ], + "examples": "- name: Use role\n include_role: ns2.col.foo\n vars:\n foo_param_1: foobar\n foo_param_2: 23", "options": { "foo_param_1": { "description": [ diff --git a/tests/functional/ansible-doc-cache-all.json b/tests/functional/ansible-doc-cache-all.json index 0a8533e0..bc13ded8 100644 --- a/tests/functional/ansible-doc-cache-all.json +++ b/tests/functional/ansible-doc-cache-all.json @@ -23312,6 +23312,7 @@ "description": [ "This is the baz entrypoint of the bar role." ], + "examples": "An example.", "short_description": "Bar role, baz entrypoint \u30c6\u30b9\u30c8\u30ed\u30fc\u30eb" }, "main": { @@ -23365,6 +23366,7 @@ "This is the foo role.", "If you set O(foo_param_1) while O(foo_param_2=3), this might behave funny." ], + "examples": "- name: Use role\n include_role: ns2.col.foo\n vars:\n foo_param_1: foobar\n foo_param_2: 23", "options": { "foo_param_1": { "description": [ diff --git a/tests/functional/ansible-doc-cache-ansible.builtin-ns.col2-ns2.col.json b/tests/functional/ansible-doc-cache-ansible.builtin-ns.col2-ns2.col.json index 77f05a91..fc892ea9 100644 --- a/tests/functional/ansible-doc-cache-ansible.builtin-ns.col2-ns2.col.json +++ b/tests/functional/ansible-doc-cache-ansible.builtin-ns.col2-ns2.col.json @@ -23194,6 +23194,7 @@ "description": [ "This is the baz entrypoint of the bar role." ], + "examples": "An example.", "short_description": "Bar role, baz entrypoint \u30c6\u30b9\u30c8\u30ed\u30fc\u30eb" }, "main": { @@ -23247,6 +23248,7 @@ "This is the foo role.", "If you set O(foo_param_1) while O(foo_param_2=3), this might behave funny." ], + "examples": "- name: Use role\n include_role: ns2.col.foo\n vars:\n foo_param_1: foobar\n foo_param_2: 23", "options": { "foo_param_1": { "description": [ diff --git a/tests/functional/ansible-doc-cache-ansible.builtin-ns2.col.json b/tests/functional/ansible-doc-cache-ansible.builtin-ns2.col.json index b33523ee..f353db0f 100644 --- a/tests/functional/ansible-doc-cache-ansible.builtin-ns2.col.json +++ b/tests/functional/ansible-doc-cache-ansible.builtin-ns2.col.json @@ -22835,6 +22835,7 @@ "This is the foo role.", "If you set O(foo_param_1) while O(foo_param_2=3), this might behave funny." ], + "examples": "- name: Use role\n include_role: ns2.col.foo\n vars:\n foo_param_1: foobar\n foo_param_2: 23", "options": { "foo_param_1": { "description": [ diff --git a/tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json b/tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json index 5069a988..624221ad 100644 --- a/tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json +++ b/tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json @@ -1867,6 +1867,7 @@ "description": [ "This is the baz entrypoint of the bar role." ], + "examples": "An example.", "short_description": "Bar role, baz entrypoint \u30c6\u30b9\u30c8\u30ed\u30fc\u30eb" }, "main": { @@ -1920,6 +1921,7 @@ "This is the foo role.", "If you set O(foo_param_1) while O(foo_param_2=3), this might behave funny." ], + "examples": "- name: Use role\n include_role: ns2.col.foo\n vars:\n foo_param_1: foobar\n foo_param_2: 23", "options": { "foo_param_1": { "description": [ diff --git a/tests/functional/ansible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json b/tests/functional/ansible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json index 11921b15..f4233c8a 100644 --- a/tests/functional/ansible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json +++ b/tests/functional/ansible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json @@ -1508,6 +1508,7 @@ "This is the foo role.", "If you set O(foo_param_1) while O(foo_param_2=3), this might behave funny." ], + "examples": "- name: Use role\n include_role: ns2.col.foo\n vars:\n foo_param_1: foobar\n foo_param_2: 23", "options": { "foo_param_1": { "description": [ diff --git a/tests/functional/ansible-doc-cache-ns.col2.json b/tests/functional/ansible-doc-cache-ns.col2.json index 3f8c3525..a6005f78 100644 --- a/tests/functional/ansible-doc-cache-ns.col2.json +++ b/tests/functional/ansible-doc-cache-ns.col2.json @@ -1073,6 +1073,7 @@ "description": [ "This is the baz entrypoint of the bar role." ], + "examples": "An example.", "short_description": "Bar role, baz entrypoint \u30c6\u30b9\u30c8\u30ed\u30fc\u30eb" }, "main": { diff --git a/tests/functional/ansible-doc-cache-ns2.col.json b/tests/functional/ansible-doc-cache-ns2.col.json index 9b055602..ad0142ed 100644 --- a/tests/functional/ansible-doc-cache-ns2.col.json +++ b/tests/functional/ansible-doc-cache-ns2.col.json @@ -1390,6 +1390,7 @@ "This is the foo role.", "If you set O(foo_param_1) while O(foo_param_2=3), this might behave funny." ], + "examples": "- name: Use role\n include_role: ns2.col.foo\n vars:\n foo_param_1: foobar\n foo_param_2: 23", "options": { "foo_param_1": { "description": [ diff --git a/tests/functional/baseline-default/collections/ns/col2/bar_role.rst b/tests/functional/baseline-default/collections/ns/col2/bar_role.rst index fe8bf547..ee1ac622 100644 --- a/tests/functional/baseline-default/collections/ns/col2/bar_role.rst +++ b/tests/functional/baseline-default/collections/ns/col2/bar_role.rst @@ -68,6 +68,14 @@ Synopsis .. Seealso +Examples +-------- + +.. code-block:: yaml+jinja + + An example. + + .. Entry point title @@ -114,6 +122,7 @@ See Also \ :ref:`ns2.col.foo `\ lookup plugin The official documentation on the **ns2.col.foo** lookup plugin. + Authors ^^^^^^^ diff --git a/tests/functional/baseline-default/collections/ns2/col/foo_role.rst b/tests/functional/baseline-default/collections/ns2/col/foo_role.rst index dd66290c..c90dcaae 100644 --- a/tests/functional/baseline-default/collections/ns2/col/foo_role.rst +++ b/tests/functional/baseline-default/collections/ns2/col/foo_role.rst @@ -285,6 +285,18 @@ See Also \ :ref:`ns2.col.foo `\ The official documentation on the **ns2.col.foo** module. +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Use role + include_role: ns2.col.foo + vars: + foo_param_1: foobar + foo_param_2: 23 + + Authors ^^^^^^^ diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns/col2/bar_role.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns/col2/bar_role.rst index fe8bf547..ee1ac622 100644 --- a/tests/functional/baseline-no-breadcrumbs/collections/ns/col2/bar_role.rst +++ b/tests/functional/baseline-no-breadcrumbs/collections/ns/col2/bar_role.rst @@ -68,6 +68,14 @@ Synopsis .. Seealso +Examples +-------- + +.. code-block:: yaml+jinja + + An example. + + .. Entry point title @@ -114,6 +122,7 @@ See Also \ :ref:`ns2.col.foo `\ lookup plugin The official documentation on the **ns2.col.foo** lookup plugin. + Authors ^^^^^^^ diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_role.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_role.rst index dd66290c..c90dcaae 100644 --- a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_role.rst +++ b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_role.rst @@ -285,6 +285,18 @@ See Also \ :ref:`ns2.col.foo `\ The official documentation on the **ns2.col.foo** module. +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Use role + include_role: ns2.col.foo + vars: + foo_param_1: foobar + foo_param_2: 23 + + Authors ^^^^^^^ diff --git a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_role.rst b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_role.rst index dd66290c..c90dcaae 100644 --- a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_role.rst +++ b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_role.rst @@ -285,6 +285,18 @@ See Also \ :ref:`ns2.col.foo `\ The official documentation on the **ns2.col.foo** module. +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Use role + include_role: ns2.col.foo + vars: + foo_param_1: foobar + foo_param_2: 23 + + Authors ^^^^^^^ diff --git a/tests/functional/baseline-simplified-rst-squash-hierarchy/foo_role.rst b/tests/functional/baseline-simplified-rst-squash-hierarchy/foo_role.rst index a509eeb9..cb5b3b59 100644 --- a/tests/functional/baseline-simplified-rst-squash-hierarchy/foo_role.rst +++ b/tests/functional/baseline-simplified-rst-squash-hierarchy/foo_role.rst @@ -136,6 +136,18 @@ See Also The official documentation on the **ns2.col.foo** module. +Examples +-------- + +.. code-block:: yaml + + - name: Use role + include_role: ns2.col.foo + vars: + foo_param_1: foobar + foo_param_2: 23 + + Authors ^^^^^^^ diff --git a/tests/functional/baseline-simplified-rst/collections/ns/col2/bar_role.rst b/tests/functional/baseline-simplified-rst/collections/ns/col2/bar_role.rst index 857ec754..5d1881a3 100644 --- a/tests/functional/baseline-simplified-rst/collections/ns/col2/bar_role.rst +++ b/tests/functional/baseline-simplified-rst/collections/ns/col2/bar_role.rst @@ -33,6 +33,14 @@ Synopsis +Examples +-------- + +.. code-block:: yaml + + An example. + + Entry point ``main`` -- Bar role @@ -62,6 +70,7 @@ See Also The official documentation on the **ns2.col.foo** lookup plugin. + Authors ^^^^^^^ diff --git a/tests/functional/baseline-simplified-rst/collections/ns2/col/foo_role.rst b/tests/functional/baseline-simplified-rst/collections/ns2/col/foo_role.rst index a509eeb9..cb5b3b59 100644 --- a/tests/functional/baseline-simplified-rst/collections/ns2/col/foo_role.rst +++ b/tests/functional/baseline-simplified-rst/collections/ns2/col/foo_role.rst @@ -136,6 +136,18 @@ See Also The official documentation on the **ns2.col.foo** module. +Examples +-------- + +.. code-block:: yaml + + - name: Use role + include_role: ns2.col.foo + vars: + foo_param_1: foobar + foo_param_2: 23 + + Authors ^^^^^^^ diff --git a/tests/functional/baseline-squash-hierarchy/foo_role.rst b/tests/functional/baseline-squash-hierarchy/foo_role.rst index dd66290c..c90dcaae 100644 --- a/tests/functional/baseline-squash-hierarchy/foo_role.rst +++ b/tests/functional/baseline-squash-hierarchy/foo_role.rst @@ -285,6 +285,18 @@ See Also \ :ref:`ns2.col.foo `\ The official documentation on the **ns2.col.foo** module. +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Use role + include_role: ns2.col.foo + vars: + foo_param_1: foobar + foo_param_2: 23 + + Authors ^^^^^^^ diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_role.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_role.rst index 6ce3601c..bd8e6e0c 100644 --- a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_role.rst +++ b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_role.rst @@ -238,6 +238,18 @@ See Also \ :ref:`ns2.col.foo `\ The official documentation on the **ns2.col.foo** module. +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Use role + include_role: ns2.col.foo + vars: + foo_param_1: foobar + foo_param_2: 23 + + Authors ^^^^^^^ diff --git a/tests/functional/collections/ansible_collections/ns/col2/roles/bar/meta/argument_specs.yml b/tests/functional/collections/ansible_collections/ns/col2/roles/bar/meta/argument_specs.yml index 9f982fad..3365a17e 100644 --- a/tests/functional/collections/ansible_collections/ns/col2/roles/bar/meta/argument_specs.yml +++ b/tests/functional/collections/ansible_collections/ns/col2/roles/bar/meta/argument_specs.yml @@ -20,3 +20,4 @@ argument_specs: short_description: Bar role, baz entrypoint テストロール description: - This is the baz entrypoint of the bar role. + examples: An example. diff --git a/tests/functional/collections/ansible_collections/ns2/col/roles/foo/meta/argument_specs.yml b/tests/functional/collections/ansible_collections/ns2/col/roles/foo/meta/argument_specs.yml index 5223f82d..0df37139 100644 --- a/tests/functional/collections/ansible_collections/ns2/col/roles/foo/meta/argument_specs.yml +++ b/tests/functional/collections/ansible_collections/ns2/col/roles/foo/meta/argument_specs.yml @@ -42,3 +42,9 @@ argument_specs: I don't know of any alternative. + examples: |- + - name: Use role + include_role: ns2.col.foo + vars: + foo_param_1: foobar + foo_param_2: 23 From 071c42ac0f69b98ed7cf8cf526b3090a99e5df52 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 12 Feb 2024 20:31:16 +0100 Subject: [PATCH 2/2] Allow other examples formats. --- src/antsibull_docs/data/docsite/ansible-docsite/role.rst.j2 | 2 +- src/antsibull_docs/data/docsite/simplified-rst/role.rst.j2 | 2 +- src/antsibull_docs/schemas/docs/role.py | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/antsibull_docs/data/docsite/ansible-docsite/role.rst.j2 b/src/antsibull_docs/data/docsite/ansible-docsite/role.rst.j2 index 421a0adc..18c1f73f 100644 --- a/src/antsibull_docs/data/docsite/ansible-docsite/role.rst.j2 +++ b/src/antsibull_docs/data/docsite/ansible-docsite/role.rst.j2 @@ -193,7 +193,7 @@ See Also Examples -------- -.. code-block:: yaml+jinja +.. code-block:: @{ ep_doc['examples_format'] | rst_format(for_sphinx=true) }@ @{ ep_doc['examples'] | indent(4, True) }@ diff --git a/src/antsibull_docs/data/docsite/simplified-rst/role.rst.j2 b/src/antsibull_docs/data/docsite/simplified-rst/role.rst.j2 index 2832b0f8..54f2065d 100644 --- a/src/antsibull_docs/data/docsite/simplified-rst/role.rst.j2 +++ b/src/antsibull_docs/data/docsite/simplified-rst/role.rst.j2 @@ -150,7 +150,7 @@ See Also Examples -------- -.. code-block:: yaml +.. code-block:: @{ ep_doc['examples_format'] | rst_format }@ @{ ep_doc['examples'] | indent(4, True) }@ diff --git a/src/antsibull_docs/schemas/docs/role.py b/src/antsibull_docs/schemas/docs/role.py index d62d893d..e6c357c8 100644 --- a/src/antsibull_docs/schemas/docs/role.py +++ b/src/antsibull_docs/schemas/docs/role.py @@ -26,6 +26,7 @@ SeeAlsoSchemaT, list_from_scalars, ) +from .plugin import PluginExamplesSchema _SENTINEL = object() @@ -49,7 +50,7 @@ class RoleOptionsSchema(OptionsSchema): options: dict[str, "InnerRoleOptionsSchema"] = {} -class RoleEntrypointSchema(BaseModel): +class RoleEntrypointSchema(PluginExamplesSchema, BaseModel): """Documentation for role entrypoints.""" description: list[str] @@ -65,7 +66,6 @@ class RoleEntrypointSchema(BaseModel): str, t.Union[AttributeSchema, AttributeSchemaActionGroup, AttributeSchemaPlatform], ] = {} - examples: str = "" options: dict[str, RoleOptionsSchema] = {}