cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Issue 73792: Removed mentions of R() and M() (#74708)

Browse source 
* 73792: Removed mentions of R and M
This commit is contained in:
Lydie 2021-05-14 15:48:21 -04:00 committed by GitHub
parent 8d3dce49bf
commit bf9944266c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 2 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
docs/docsite/rst/dev_guide/developing_modules_documenting.rst
View file

@ -235,8 +235,6 @@ You can link from your module documentation to other module docs, other resource
* ``L()`` for links with a heading. For example: ``See L(Ansible Automation Platform,https://www.ansible.com/products/automation-platform).`` As of Ansible 2.10, do not use ``L()`` for relative links between Ansible documentation and collection documentation. * ``L()`` for links with a heading. For example: ``See L(Ansible Automation Platform,https://www.ansible.com/products/automation-platform).`` As of Ansible 2.10, do not use ``L()`` for relative links between Ansible documentation and collection documentation.
* ``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/automation-platform) for an overview.`` * ``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/automation-platform) for an overview.``
* ``R()`` for cross-references with a heading (added in Ansible 2.10). For example: ``See R(Cisco IOS Platform Guide,ios_platform_options)``. Use the RST anchor for the cross-reference. See :ref:`adding_anchors_rst` for details.
* ``M()`` for module names. For example: ``See also M(ansible.builtin.yum) or M(community.general.apt_rpm)``.
There are also some macros which do not create links but we use them to display certain types of There are also some macros which do not create links but we use them to display certain types of
content in a uniform way: content in a uniform way:
@ -249,16 +247,13 @@ content in a uniform way:
.. note:: .. note::
For links between modules and documentation within a collection, you can use any of the options above. For links outside of your collection, use ``R()`` if available. Otherwise, use ``U()`` or ``L()`` with full URLs (not relative links). For modules, use ``M()`` with the FQCN or ``ansible.builtin`` as shown in the example. If you are creating your own documentation site, you will need to use the `intersphinx extension <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_ to convert ``R()`` and ``M()`` to the correct links. For links between modules and documentation within a collection, you can use either of the options above. Use ``U()`` or ``L()`` with full URLs (not relative links).
.. note:: .. note::
- To refer to a group of modules in a collection, use ``R()``. When a collection is not the right granularity, use ``C(..)``: - When a collection is not the right granularity, use ``C(..)``:
- ``Refer to the R(kubernetes.core collection, plugins_in_kubernetes.core) for information on managing kubernetes clusters.``
- ``The C(win_*) modules (spread across several collections) allow you to manage various aspects of windows hosts.`` - ``The C(win_*) modules (spread across several collections) allow you to manage various aspects of windows hosts.``
.. note:: .. note::
Because it stands out better, use ``seealso`` for general references over the use of notes or adding links to the description. Because it stands out better, use ``seealso`` for general references over the use of notes or adding links to the description.