Support role extension for semantic markup. (#80305)

5 files changed, 17 insertions, 4 deletions

diff --git a/changelogs/fragments/80305-ansible-doc-role-semantic-markup.yml b/changelogs/fragments/80305-ansible-doc-role-semantic-markup.yml
new file mode 100644
index 0000000000..f3753b7192
--- /dev/null
+++ b/changelogs/fragments/80305-ansible-doc-role-semantic-markup.yml
@@ -0,0 +1,2 @@
+minor_changes:
+  - "ansible-doc - support role extension for semantic markup spec so that ``O()`` and ``RV()`` referring to role entrypoints are rendered more readable (https://github.com/ansible/ansible/pull/80305)."
diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py
index 97e6766336..124eadc920 100755
--- a/lib/ansible/cli/doc.py
+++ b/lib/ansible/cli/doc.py
@@ -411,10 +411,17 @@ class DocCLI(CLI, RoleMixin):
             plugin_fqcn = plugin_type = ''
         else:
             plugin_fqcn = plugin_type = ''
+        entrypoint = None
+        if ':' in text:
+            entrypoint, text = text.split(':', 1)
         if value is not None:
             text = f"{text}={value}"
         if plugin_fqcn and plugin_type:
-            return f"`{text}' (of {plugin_type} {plugin_fqcn})"
+            plugin_suffix = '' if plugin_type in ('role', 'module', 'playbook') else ' plugin'
+            plugin = f"{plugin_type}{plugin_suffix} {plugin_fqcn}"
+            if plugin_type == 'role' and entrypoint is not None:
+                plugin = f"{plugin}, {entrypoint} entrypoint"
+            return f"`{text}' (of {plugin})"
         return f"`{text}'"
 
     @classmethod
diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py
index 12a3f0a927..71ae7c1145 100644
--- a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py
+++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py
@@ -9,6 +9,7 @@ module: randommodule
 short_description: A random module
 description:
     - A random module.
+    - See O(foo.bar.baz#role:main:foo=bar) for how this is used in the P(foo.bar.baz#role)'s C(main) entrypoint.
 author:
     - Ansible Core Team
 version_added: 1.0.0
diff --git a/test/integration/targets/ansible-doc/randommodule-text.output b/test/integration/targets/ansible-doc/randommodule-text.output
index 347b2b21bc..5a7ff1ce9f 100644
--- a/test/integration/targets/ansible-doc/randommodule-text.output
+++ b/test/integration/targets/ansible-doc/randommodule-text.output
@@ -1,6 +1,8 @@
 > TESTNS.TESTCOL.RANDOMMODULE    (./collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py)
 
-        A random module.
+        A random module. See `foo=bar' (of role foo.bar.baz, main
+        entrypoint) for how this is used in the [foo.bar.baz]'s `main'
+        entrypoint.
 
 ADDED IN: version 1.0.0 of testns.testcol
 
@@ -104,7 +106,7 @@ RETURN VALUES:
         This should be in the middle.
         Has some more data.
         Check out `m_middle.suboption' and compare it to `a_first=foo'
-        and `value' (of lookup community.general.foo).
+        and `value' (of lookup plugin community.general.foo).
         returned: success and 1st of month
         type: dict
 
diff --git a/test/integration/targets/ansible-doc/randommodule.output b/test/integration/targets/ansible-doc/randommodule.output
index d97dde8bdc..aad2cc4403 100644
--- a/test/integration/targets/ansible-doc/randommodule.output
+++ b/test/integration/targets/ansible-doc/randommodule.output
@@ -12,7 +12,8 @@
                 "why": "Test deprecation"
             },
             "description": [
-                "A random module."
+                "A random module.",
+                "See O(foo.bar.baz#role:main:foo=bar) for how this is used in the P(foo.bar.baz#role)'s C(main) entrypoint."
             ],
             "filename": "./collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py",
             "has_action": false,