From ddaa539ab115df10cfc34682049f40b7907b95f3 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Tue, 11 May 2021 11:31:20 -0400 Subject: [PATCH] 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 --- .../fragments/improve_derstification.yml | 2 ++ lib/ansible/cli/doc.py | 22 ++++++++++--------- lib/ansible/keyword_desc.yml | 13 ++--------- test/units/cli/test_doc.py | 5 +++++ 4 files changed, 21 insertions(+), 21 deletions(-) create mode 100644 changelogs/fragments/improve_derstification.yml diff --git a/changelogs/fragments/improve_derstification.yml b/changelogs/fragments/improve_derstification.yml new file mode 100644 index 00000000000..a80f19f2475 --- /dev/null +++ b/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. diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py index f0613647c98..e6444f145f8 100644 --- a/lib/ansible/cli/doc.py +++ b/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 diff --git a/lib/ansible/keyword_desc.yml b/lib/ansible/keyword_desc.yml index 3139b5a6dd3..f0e076c5bc5 100644 --- a/lib/ansible/keyword_desc.yml +++ b/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`. diff --git a/test/units/cli/test_doc.py b/test/units/cli/test_doc.py index 58feadf8b8b..5cdf974b4b8 100644 --- a/test/units/cli/test_doc.py +++ b/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 ', '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', }