Keywords docs (#32807)

* Fixup keyword dumping

* Clarify introductory text
* Turn links in the keyword description into seealso entries in the rst.

* Have plugin_formatter cleanup trailing whitespace

The indent filter in jinja2 < 2.10 indents blank lines by default which
leads to trailing whitespace.  Cleanup after that filter.

* Edits

* Copy edit

docs/docsite/keyword_desc.yml

@@ -1,52 +1,68 @@
-accelerate: DEPRECATED, set to True to use accelerate connection plugin.
-accelerate_ipv6: "DEPRECATED, set to True to force accelerate plugin to use ipv6 for it's connection."
-accelerate_port: DEPRECATED, set to override default port use for accelerate connection.
+accelerate: "*DEPRECATED*, set to True to use accelerate connection plugin."
+accelerate_ipv6: "*DEPRECATED*, set to True to force accelerate plugin to use ipv6 for its connection."
+accelerate_port: "*DEPRECATED*, set to override default port use for accelerate connection."
 action: "The 'action' to execute for a task, it normally translates into a C(module) or action plugin."
-args: DEPRECATED, A secondary way to add arguments into a task, it takes a dictionary in which keys map to options and values .. well you get it.
+args: "*DEPRECATED*, A secondary way to add arguments into a task. Takes a dictionary in which keys map to options and values."
 always: List of tasks, in a block, that execute no matter if there is an error in the block or not.
-always_run: DEPRECATED, forces a task to run even in check mode, use :term:`check_mode` directive instead.
+always_run: "*DEPRECATED*, forces a task to run even in check mode. Use :term:`check_mode` directive instead."
 any_errors_fatal: Force any un-handled task errors on any host to propagate to all hosts and end the play.
 async: Run a task asyncronouslly if the C(action) supports this.
 become: Boolean that controls if privilege escalation is used or not on :term:`Task` execution.
 become_flags: A string of flag(s) to pass to the privilege escalation program when :term:`become` is True.
-become_method: Which method of privilege escalation to use. i.e. sudo/su/etc.
-become_user: "User that you 'become' after using privilege escalation, the remote/login user must have permissions to become this user."
+become_method: Which method of privilege escalation to use (such as sudo or su).
+become_user: "User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user."
 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"
-connection: Allows you to change the connection plugin used for tasks to execute on the target.
-delay: Number of seconds to delay between retries, this setting is only used in combination with :term:`until`.
-delegate_facts: Boolean that allows you to apply facts to delegated host instead of inventory_hostname.
-delegate_to: Host to execute task instead of the target (inventory_hostname), connection vars from the delegated host will also be used for the task.
+check_mode: |
+    A boolean that controls if a task is executed in 'check' mode
+
+    .. seealso:: :ref:`check_mode_dry`
+
+connection: |
+    Allows you to change the connection plugin used for tasks to execute on the target.
+
+    .. seealso:: :ref:`using_connection`
+
+delay: Number of seconds to delay between retries. This setting is only used in combination with :term:`until`.
+delegate_facts: Boolean that allows you to apply facts to a delegated host instead of inventory_hostname.
+delegate_to: Host to execute task instead of the target (inventory_hostname). Connection vars from the delegated host will also be used for the task.
 diff: "Toggle to make tasks return 'diff' information or not."
 environment: A dictionary that gets converted into environment vars to be provided for the task upon execution.
 fact_path: Set the fact path option for the fact gathering plugin controlled by :term:`gather_facts`.
 failed_when: "Conditional expression that overrides the task's normal 'failed' status."
-force_handlers: Will force notified handler execution for hosts even if they failed during the play, it will not trigger if the play itself fails.
+force_handlers: Will force notified handler execution for hosts even if they failed during the play. Will not trigger if the play itself fails.
 gather_facts: "A boolean that controls if the play will automatically run the 'setup' task to gather facts for the hosts."
 gather_subset: Allows you to pass subset options to the  fact gathering plugin controlled by :term:`gather_facts`.
 gather_timeout: Allows you to set the timeout for the fact gathering plugin controlled by :term:`gather_facts`.
-handlers: "A section with tasks that are treated as handlers, these won't get executed normally, only when notified. After each section of tasks is complete."
+handlers: "A section with tasks that are treated as handlers, these won't get executed normally, only when notified after each section of tasks is complete."
 hosts: "A list of groups, hosts or host pattern that translates into a list of hosts that are the play's target."
 ignore_errors: Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
 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 see http://docs.ansible.com/ansible/latest/playbooks_loops.html#loop-control for details."
+loop_control: |
+    Several keys here allow you to modify/set loop behaviour in a task.
+
+    .. seealso:: :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.
-name: "It's a name, works mostly for documentation, in the case of tasks/handlers it can be an identifier."
+name: "Identifier. Can be used for documentation, in or tasks/handlers."
 no_log: Boolean that controls information disclosure.
-notify: "list of handlers to notify when the task returns a 'changed=True' status."
+notify: "List of handlers to notify when the task returns a 'changed=True' status."
 order: Controls the sorting of hosts as they are used for executing the play. Possible values are inventory (default), sorted, reverse_sorted, reverse_inventory and shuffle.
 poll: Sets the polling interval in seconds for async tasks (default 10s).
 port: Used to override the default port used in a connection.
 post_tasks: A list of tasks to execute after the :term:`tasks` section.
 pre_tasks: A list of tasks to execute before :term:`roles`.
-remote_user: User used to log into the target via the connection plugin. AKA login user.
+remote_user: User used to log into the target via the connection plugin.
 register: Name of variable that will contain task status and module return data.
 rescue: List of tasks in a :term:`block` that run if there is a task error in the main :term:`block` list.
 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 execute on the first host available and will also apply any facts to all active hosts.
-serial: Defines the 'batch' of hosts to execute the current play until the end.
+serial: |
+    Explicitly define how Ansible batches the execution of the current play on the play's target
+
+    .. seealso:: :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`.