Use new :ansoptref: and :ansretvalref: roles. (#3306)

(cherry picked from commit daef4fd)

Author: felixfontein

docs/docsite/rst/dev_guide/developing_program_flow_modules.rst

@@ -502,16 +502,16 @@ Modules can access this parameter by using the public ``tmpdir`` property. The `
 The directory name is generated randomly, and the the root of the directory is determined by one of these:
 
 * :ref:`DEFAULT_LOCAL_TMP`
-* `remote_tmp <https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-remote_tmp>`_
-* `system_tmpdirs <https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-system_tmpdirs>`_
+* :ansoptref:`remote_tmp <ansible.builtin.sh#shell:remote_tmp>`
+* :ansoptref:`system_tmpdirs <ansible.builtin.sh#shell:system_tmpdirs>`
 
 As a result, using the ``ansible.cfg`` configuration file to activate or customize this setting will not guarantee that you control the full value.
 
 
 _ansible_remote_tmp
 ^^^^^^^^^^^^^^^^^^^
 
-The module's ``tmpdir`` property creates a randomized directory name in this directory if the action plugin did not set ``_ansible_tmpdir``. For more details, see the `remote_tmp <https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-remote_tmp>`_ parameter of the shell plugin.
+The module's ``tmpdir`` property creates a randomized directory name in this directory if the action plugin did not set ``_ansible_tmpdir``. For more details, see the :ansoptref:`remote_tmp <ansible.builtin.sh#shell:remote_tmp>` parameter of the shell plugin.
 
 
 .. _flow_module_return_values:

docs/docsite/rst/dev_guide/style_guide/index.rst

@@ -251,14 +251,21 @@ Instead of ``#module``, you can also specify ``#<plugin_type>`` to reference to
 Adding links to module and plugin options and return values
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Use the ``:ansopt:`` and ``:ansretval:`` roles to reference options and return values of modules and plugins:
+Use the ``:ansopt:`` and ``:ansretval:`` roles to reference options and return values of modules and plugins while showing the option's resp. return value's name and optionally a value.
+Use the ``:ansoptref:`` and ``:ansretvalref:`` roles to reference options and return values of modules and plugins while displaying a provided title.
+
+The following example shows their usage:
 
 .. code-block:: rst
 
   :ansopt:`ansible.builtin.file#module:path` references the ``path`` parameter of the
   ``ansible.builtin.file`` module; :ansopt:`ansible.builtin.file#module:path=/root/.ssh/known_hosts`
   shows the assignment ``path=/root/.ssh/known_hosts`` as a clickable link.
 
+  You can :ansoptref:`provide a path <ansible.builtin.file#module:path>`
+  to the :ansplugin:`ansible.builtin.file#module`; its value is
+  :ansretvalref:`returned as a return value <ansible.builtin.file#module:path>`.
+
   :ansretval:`ansible.builtin.stat#module:stat.exists` references the ``stat.exists`` return value
   of the ``ansible.builtin.stat`` module. You can also use ``=`` as for option values:
   :ansretval:`ansible.builtin.stat#module:stat.exists=true` shows ``stat.exists=true``.
@@ -267,21 +274,26 @@ Use the ``:ansopt:`` and ``:ansretval:`` roles to reference options and return v
   assignment without a link; the same is true for return values: :ansretval:`foo` and
   :ansretval:`foo=bar`.
 
-This displays as
-":ansopt:`ansible.builtin.file#module:path` references the ``path`` parameter of the
-``ansible.builtin.file`` module; :ansopt:`ansible.builtin.file#module:path=/root/.ssh/known_hosts`
-shows the assignment ``path=/root/.ssh/known_hosts`` as a clickable link."
-and
-":ansretval:`ansible.builtin.stat#module:stat.exists` references the ``stat.exists`` return value
-of the ``ansible.builtin.stat`` module. You can also use ``=`` as for option values:
-:ansretval:`ansible.builtin.stat#module:stat.exists=true` shows ``stat.exists=true``."
-and
-":ansopt:`foo` and :ansopt:`foo=bar` use the same markup for an option and an option
-assignment without a link; the same is true for return values: :ansretval:`foo` and
-:ansretval:`foo=bar`.".
+This displays as:
+
+  :ansopt:`ansible.builtin.file#module:path` references the ``path`` parameter of the
+  ``ansible.builtin.file`` module; :ansopt:`ansible.builtin.file#module:path=/root/.ssh/known_hosts`
+  shows the assignment ``path=/root/.ssh/known_hosts`` as a clickable link.
+
+  You can :ansoptref:`provide a path <ansible.builtin.file#module:path>`
+  to the :ansplugin:`ansible.builtin.file#module`; its value is
+  :ansretvalref:`returned as a return value <ansible.builtin.file#module:path>`.
+
+  :ansretval:`ansible.builtin.stat#module:stat.exists` references the ``stat.exists`` return value
+  of the ``ansible.builtin.stat`` module. You can also use ``=`` as for option values:
+  :ansretval:`ansible.builtin.stat#module:stat.exists=true` shows ``stat.exists=true``.
+
+  :ansopt:`foo` and :ansopt:`foo=bar` use the same markup for an option and an option
+  assignment without a link; the same is true for return values: :ansretval:`foo` and
+  :ansretval:`foo=bar`.
 
 For both option and return values, ``.`` is used to reference suboptions and contained return values.
-Array stubs (``[...]``) can be used to indicate that something is a list, for example the ``:retval:``
+Array stubs (``[...]``) can be used to indicate that something is a list, for example the ``:ansretval:``
 argument ``ansible.builtin.service_facts#module:ansible_facts.services['systemd'].state`` references
 the ``ansible_facts.services.state`` return value of the ``ansible.builtin.service_facts`` module
 (:ansretval:`ansible.builtin.service_facts#module:ansible_facts.services['systemd'].state`).

docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst

@@ -172,8 +172,9 @@ to check ``world_readable_temp`` per below.
 If ``ansible_common_remote_group`` is **not** set and the chown above it failed,
 or if ``ansible_common_remote_group`` *is* set but the :command:`chgrp` (or
 following group-permissions :command:`chmod`) returned a non-successful exit
-code, Ansible will lastly check `the world_readable_temp option`_. If this is
-set, Ansible will place the module file in a world-readable temporary directory,
+code, Ansible will lastly check
+:ansoptref:`the world_readable_temp option <ansible.builtin.sh#shell:world_readable_temp>`.
+If this is set, Ansible will place the module file in a world-readable temporary directory,
 with world-readable permissions to allow the ``become_user`` (and incidentally
 any other user on the system) to read the contents of the file. **If any of the
 parameters passed to the module are sensitive in nature, and you do not trust
@@ -198,8 +199,9 @@ Several ways exist to avoid the above logic flow entirely:
 .. warning:: Although the Solaris ZFS filesystem has filesystem ACLs, the ACLs
     are not POSIX.1e filesystem acls (they are NFSv4 ACLs instead).  Ansible
     cannot use these ACLs to manage its temp file permissions so you may have
-    to resort to `the world_readable_temp option`_ if the remote machines
-    use ZFS.
+    to resort to
+    :ansoptref:`the world_readable_temp option <ansible.builtin.sh#shell:world_readable_temp>`
+    if the remote machines use ZFS.
 
 .. versionchanged:: 2.1
 
@@ -208,13 +210,12 @@ Ansible defaults to issuing an error if it cannot execute securely with ``become
 If you cannot use pipelining or POSIX ACLs, must connect as an unprivileged user,
 must use ``become`` to execute as a different unprivileged user,
 and decide that your managed nodes are secure enough for the
-modules you want to run there to be world readable, you can turn on `the world_readable_temp option`_, which will change this from an error into
-a warning and allow the task to run as it did prior to 2.1.
+modules you want to run there to be world readable, you can turn on
+:ansoptref:`the world_readable_temp option <ansible.builtin.sh#shell:world_readable_temp>`,
+which will change this from an error into a warning and allow the task to run as it did prior to 2.1.
 
 .. versionchanged:: 2.10
 
-.. _the world_readable_temp option: https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-world_readable_temp
-
 Ansible 2.10 introduces the above-mentioned ``ansible_common_remote_group``
 fallback. As mentioned above, if enabled, it is used when ``remote_user`` and
 ``become_user`` are both unprivileged users. Refer to the text above for details