Fix wording for :ref|term: substitution

changelogs/fragments/fix_adoc_text.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansible-doc will not add 'website for' in ":ref:" substitutions as it made them confusing.

lib/ansible/cli/doc.py

@@ -405,10 +405,10 @@ def tty_ify(cls, text):
         t = cls._RULER.sub("\n{0}\n".format("-" * 13), t)   # HORIZONTALLINE => -------
 
         # remove rst
-        t = cls._RST_SEEALSO.sub(r"See website for:", t)   # seealso is special and need to break
-        t = cls._RST_NOTE.sub(r"Note:", t)                 # .. note:: to note:
-        t = cls._RST_ROLES.sub(r"website for `", t)        # remove :ref: and other tags
-        t = cls._RST_DIRECTIVES.sub(r"", t)                # remove .. stuff:: in general
+        t = cls._RST_SEEALSO.sub(r"See also:", t)   # seealso to See also:
+        t = cls._RST_NOTE.sub(r"Note:", t)          # .. note:: to note:
+        t = cls._RST_ROLES.sub(r"`", t)             # remove :ref: and other tags, keep tilde to match ending one
+        t = cls._RST_DIRECTIVES.sub(r"", t)         # remove .. stuff:: in general
 
         return t
 

test/units/cli/test_doc.py

@@ -29,9 +29,9 @@
     'L(the user guide, https://docs.ansible.com/)': 'the user guide <https://docs.ansible.com/>',
     'R(the user guide, user-guide)': 'the user guide',
     # de-rsty refs and anchors
-    'yolo :ref:`my boy` does stuff': 'yolo website for `my boy` does stuff',
-    '.. seealso:: Something amazing': 'See website for: Something amazing',
-    '.. seealso:: Troublesome multiline\n Stuff goes htere': 'See website for: Troublesome multiline\n Stuff goes htere',
+    'yolo :ref:`my boy` does stuff': 'yolo `my boy` does stuff',
+    '.. seealso:: Something amazing': 'See also: Something amazing',
+    '.. seealso:: Troublesome multiline\n Stuff goes htere': 'See also: Troublesome multiline\n Stuff goes htere',
     '.. note:: boring stuff': 'Note: boring stuff',
 }