Better handling of rstisms in ansible-doc (#74596)

* Better handling of rstisms

  replace tags more intelligently to make things more readable
  unit tests + minor adjustments

changelogs/fragments/improve_derstification.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible-doc, improve handling of rstisms, try to make the display more meaningfull for the terminal users.

lib/ansible/cli/doc.py

@@ -354,10 +354,10 @@ class DocCLI(CLI, RoleMixin):
     _RULER = re.compile(r"\bHORIZONTALLINE\b")
 
     # rst specific
-    _REFTAG = re.compile(r":ref:")
-    _TERM = re.compile(r":term:")
-    _NOTES = re.compile(r".. note:")
-    _SEEALSO = re.compile(r"^\s*.. seealso:.*$", re.MULTILINE)
+    _RST_NOTE = re.compile(r".. note::")
+    _RST_SEEALSO = re.compile(r".. seealso::")
+    _RST_ROLES = re.compile(r":\w+?:`")
+    _RST_DIRECTIVES = re.compile(r".. \w+?::")
 
     def __init__(self, args):
 
@@ -367,17 +367,19 @@ class DocCLI(CLI, RoleMixin):
     @classmethod
     def tty_ify(cls, text):
 
+        # general formatting
         t = cls._ITALIC.sub(r"`\1'", text)    # I(word) => `word'
         t = cls._BOLD.sub(r"*\1*", t)         # B(word) => *word*
         t = cls._MODULE.sub("[" + r"\1" + "]", t)       # M(word) => [word]
-        t = cls._REF.sub(r"\1", t)                      # R(word, sphinx-ref) => word
-        t = cls._CONST.sub("`" + r"\1" + "'", t)        # C(word) => `word'
+        t = cls._REF.sub(r"\1", t)            # R(word, sphinx-ref) => word
+        t = cls._CONST.sub(r"`\1'", t)        # C(word) => `word'
         t = cls._RULER.sub("\n{0}\n".format("-" * 13), t)   # HORIZONTALLINE => -------
 
-        t = cls._REFTAG.sub(r"", t)  # remove rst :ref:
-        t = cls._TERM.sub(r"", t)  # remove rst :term:
-        t = cls._NOTES.sub(r" Note:", t)  # nicer note
-        t = cls._SEEALSO.sub(r"", t)  # remove seealso
+        # 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
 
         # handle docsite refs
         # U(word) => word

lib/ansible/keyword_desc.yml

@@ -15,7 +15,6 @@ block: List of tasks in a block.
 changed_when: "Conditional expression that overrides the task's normal 'changed' status."
 check_mode: A boolean that controls if a task is executed in 'check' mode. See :ref:`check_mode_dry`.
 collections: |
-
     List of collection namespaces to search for modules, plugins, and roles. See :ref:`collections_using_playbook`
 
     .. note::
@@ -41,11 +40,7 @@ hosts: "A list of groups, hosts or host pattern that translates into a list of h
 ignore_errors: Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
 ignore_unreachable: Boolean that allows you to ignore task failures due to an unreachable host and continue with the play. This does not affect other task errors (see :term:`ignore_errors`) but is useful for groups of volatile/ephemeral hosts.
 loop: "Takes a list for the task to iterate over, saving each list element into the ``item`` variable (configurable via loop_control)"
-loop_control: |
-    Several keys here allow you to modify/set loop behaviour in a task.
-
-    .. seealso:: :ref:`loop_control`
-
+loop_control: Several keys here allow you to modify/set loop behaviour in a task. See :ref:`loop_control`.
 max_fail_percentage: can be used to abort the run after a given percentage of hosts in the current batch has failed. This only wokrs on linear or linear derived strategies.
 module_defaults: Specifies default parameter values for modules.
 name: "Identifier. Can be used for documentation, or in tasks/handlers."
@@ -62,11 +57,7 @@ rescue: List of tasks in a :term:`block` that run if there is a task error in th
 retries: "Number of retries before giving up in a :term:`until` loop. This setting is only used in combination with :term:`until`."
 roles: List of roles to be imported into the play
 run_once: Boolean that will bypass the host loop, forcing the task to attempt to execute on the first host available and afterwards apply any results and facts to all active hosts in the same batch.
-serial: |
-    Explicitly define how Ansible batches the execution of the current play on the play's target
-
-    .. seealso:: :ref:`rolling_update_batch_size`
-
+serial: Explicitly define how Ansible batches the execution of the current play on the play's target. See :ref:`rolling_update_batch_size`.
 strategy: Allows you to choose the connection plugin to use for the play.
 tags: Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line.
 tasks: Main list of tasks to execute in the play, they run after :term:`roles` and before :term:`post_tasks`.

test/units/cli/test_doc.py

@@ -27,6 +27,11 @@ TTY_IFY_DATA = {
     'IBM(International Business Machines)': 'IBM(International Business Machines)',
     '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',
+    '.. note:: boring stuff': 'Note: boring stuff',
 }