Implement semantic markup support for Ansible documentation in ansible-doc. (#80242)

3 files changed, 27 insertions, 20 deletions

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 f251a69f0e..9d59a7bbf2 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
@@ -3,7 +3,7 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: randommodule
 short_description: A random module
@@ -18,22 +18,22 @@ deprecated:
     removed_in: '3.0.0'
 options:
     test:
-        description: Some text.
+        description: Some text. Consider not using O(ignore:foo=bar).
         type: str
         version_added: 1.2.0
     sub:
-        description: Suboptions.
+        description: Suboptions. Contains O(sub.subtest), which can be set to V(123). You can use E(TEST_ENV) to set this.
         type: dict
         suboptions:
             subtest:
-                description: A suboption.
+                description: A suboption. Not compatible to O(ansible.builtin.copy#module:path=c:\\foo\(1\).txt).
                 type: int
                 version_added: 1.1.0
         # The following is the wrong syntax, and should not get processed
         # by add_collection_to_versions_and_dates()
         options:
             subtest2:
-                description: Another suboption.
+                description: Another suboption. Useful when P(ansible.builtin.shuffle#filter) is used with value V([a,b,\),d\\]).
                 type: float
                 version_added: 1.1.0
         # The following is not supported in modules, and should not get processed
@@ -53,7 +53,7 @@ extends_documentation_fragment:
 EXAMPLES = '''
 '''
 
-RETURN = '''
+RETURN = r'''
 z_last:
     description: A last result.
     type: str
@@ -63,7 +63,8 @@ z_last:
 m_middle:
     description:
         - This should be in the middle.
-        - Has some more data
+        - Has some more data.
+        - Check out RV(m_middle.suboption) and compare it to RV(a_first=foo) and RV(community.general.foo#lookup:value).
     type: dict
     returned: success and 1st of month
     contains:
@@ -74,7 +75,7 @@ m_middle:
             version_added: 1.4.0
 
 a_first:
-    description: A first result.
+    description: A first result. Use RV(a_first=foo\(bar\\baz\)bam).
     type: str
     returned: success
 '''
diff --git a/test/integration/targets/ansible-doc/randommodule-text.output b/test/integration/targets/ansible-doc/randommodule-text.output
index 51d7930a07..a9c426656d 100644
--- a/test/integration/targets/ansible-doc/randommodule-text.output
+++ b/test/integration/targets/ansible-doc/randommodule-text.output
@@ -14,7 +14,8 @@ DEPRECATED:
 OPTIONS (= is mandatory):
 
 - sub
-        Suboptions.
+        Suboptions. Contains `sub.subtest', which can be set to `123'.
+        You can use `TEST_ENV' to set this.
         set_via:
           env:
           - deprecated:
@@ -29,7 +30,8 @@ OPTIONS (= is mandatory):
         OPTIONS:
 
         - subtest2
-            Another suboption.
+            Another suboption. Useful when [ansible.builtin.shuffle]
+            is used with value `[a,b,),d\]'.
             default: null
             type: float
             added in: version 1.1.0
@@ -39,14 +41,15 @@ OPTIONS (= is mandatory):
         SUBOPTIONS:
 
         - subtest
-            A suboption.
+            A suboption. Not compatible to `path=c:\foo(1).txt' (of
+            module ansible.builtin.copy).
             default: null
             type: int
             added in: version 1.1.0 of testns.testcol
 
 
 - test
-        Some text.
+        Some text. Consider not using `foo=bar'.
         default: null
         type: str
         added in: version 1.2.0 of testns.testcol
@@ -74,13 +77,15 @@ EXAMPLES:
 
 RETURN VALUES:
 - a_first
-        A first result.
+        A first result. Use `a_first=foo(bar\baz)bam'.
         returned: success
         type: str
 
 - m_middle
         This should be in the middle.
-        Has some more data
+        Has some more data.
+        Check out `m_middle.suboption' and compare it to `a_first=foo'
+        and `value' (of lookup 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 25f46c3622..c882d4b368 100644
--- a/test/integration/targets/ansible-doc/randommodule.output
+++ b/test/integration/targets/ansible-doc/randommodule.output
@@ -19,7 +19,7 @@
             "module": "randommodule",
             "options": {
                 "sub": {
-                    "description": "Suboptions.",
+                    "description": "Suboptions. Contains O(sub.subtest), which can be set to V(123). You can use E(TEST_ENV) to set this.",
                     "env": [
                         {
                             "deprecated": {
@@ -34,14 +34,14 @@
                     ],
                     "options": {
                         "subtest2": {
-                            "description": "Another suboption.",
+                            "description": "Another suboption. Useful when P(ansible.builtin.shuffle#filter) is used with value V([a,b,\\),d\\\\]).",
                             "type": "float",
                             "version_added": "1.1.0"
                         }
                     },
                     "suboptions": {
                         "subtest": {
-                            "description": "A suboption.",
+                            "description": "A suboption. Not compatible to O(ansible.builtin.copy#module:path=c:\\\\foo\\(1\\).txt).",
                             "type": "int",
                             "version_added": "1.1.0",
                             "version_added_collection": "testns.testcol"
@@ -50,7 +50,7 @@
                     "type": "dict"
                 },
                 "test": {
-                    "description": "Some text.",
+                    "description": "Some text. Consider not using O(ignore:foo=bar).",
                     "type": "str",
                     "version_added": "1.2.0",
                     "version_added_collection": "testns.testcol"
@@ -78,7 +78,7 @@
         "metadata": null,
         "return": {
             "a_first": {
-                "description": "A first result.",
+                "description": "A first result. Use RV(a_first=foo\\(bar\\\\baz\\)bam).",
                 "returned": "success",
                 "type": "str"
             },
@@ -98,7 +98,8 @@
                 },
                 "description": [
                     "This should be in the middle.",
-                    "Has some more data"
+                    "Has some more data.",
+                    "Check out RV(m_middle.suboption) and compare it to RV(a_first=foo) and RV(community.general.foo#lookup:value)."
                 ],
                 "returned": "success and 1st of month",
                 "type": "dict"