Support examples for role entrypoints

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)."

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:: @{ ep_doc['examples_format'] | rst_format(for_sphinx=true) }@
+
+@{     ep_doc['examples'] | indent(4, True) }@
+
+{%   endif %}
+
 {%   if ep_doc['author'] -%}
 Authors
 ^^^^^^^

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:: @{ ep_doc['examples_format'] | rst_format }@
+
+@{     ep_doc['examples'] | indent(4, True) }@
+
+{%   endif %}
+
 {%   if ep_doc['author'] -%}
 Authors
 ^^^^^^^

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]

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": [

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": [

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": [

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": [

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": [

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": [

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": {

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": [

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 <ansible_collections.ns2.col.foo_lookup>`\  lookup plugin
        The official documentation on the **ns2.col.foo** lookup plugin.
 
+
 Authors
 ^^^^^^^
 

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

@@ -285,6 +285,18 @@ See Also
    \ :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_module>`\ 
        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
 ^^^^^^^
 

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 <ansible_collections.ns2.col.foo_lookup>`\  lookup plugin
        The official documentation on the **ns2.col.foo** lookup plugin.
 
+
 Authors
 ^^^^^^^
 

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_role.rst

@@ -285,6 +285,18 @@ See Also
    \ :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_module>`\ 
        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
 ^^^^^^^
 

tests/functional/baseline-no-indexes/collections/ns2/col/foo_role.rst

@@ -285,6 +285,18 @@ See Also
    \ :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_module>`\ 
        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
 ^^^^^^^
 

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
 ^^^^^^^
 

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
 ^^^^^^^
 

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
 ^^^^^^^
 

tests/functional/baseline-squash-hierarchy/foo_role.rst

@@ -285,6 +285,18 @@ See Also
    \ :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_module>`\ 
        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
 ^^^^^^^
 

tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_role.rst

@@ -238,6 +238,18 @@ See Also
    \ :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_module>`\ 
        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
 ^^^^^^^
 

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.

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