From 748ba96610f7d1e05c117a084e2de1023fb09d0b Mon Sep 17 00:00:00 2001
From: Sandra McCann <samccann@redhat.com>
Date: Tue, 28 Jul 2020 18:40:16 -0400
Subject: [PATCH] How to use rst :ref: for modules in collections (#70567)

---
 .../rst/dev_guide/style_guide/index.rst       | 28 ++++++++++++++++---
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/docs/docsite/rst/dev_guide/style_guide/index.rst b/docs/docsite/rst/dev_guide/style_guide/index.rst
index 975fd17a126..a50a3180e90 100644
--- a/docs/docsite/rst/dev_guide/style_guide/index.rst
+++ b/docs/docsite/rst/dev_guide/style_guide/index.rst
@@ -171,13 +171,33 @@ The second example adds custom text for the link.
 Adding links to modules and plugins
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* Module links use the module name followed by ``_module`` for the anchor.
-* Plugin links use the plugin name followed by the plugin type. For example, :ref:`enable become plugin <enable_become>`).
+Ansible 2.10 and later require the extended Fully Qualified Collection Name (FQCN) as part of the links:
+
+.. code-block:: text
+
+  ansible_collections. + FQCN + _module
+
+For example:
+
+  .. code-block:: rst
+
+   :ref:`ansible.builtin.first_found lookup plugin <ansible_collections.ansible.builtin.first_found_lookup>`
+
+displays as :ref:`ansible.builtin.first_found lookup plugin <ansible_collections.ansible.builtin.first_found_lookup>`.
+
+Modules require different suffixes from other plugins:
+
+* Module links use this extended FQCN module name with ``_module`` for the anchor.
+* Plugin links use this extended FQCN plugin name with the plugin type (``_connection`` for example).
 
 .. code-block:: rst
 
-   :ref:`this module <this_module>``
-   :ref:`that connection plugin <that_connection>`
+   :ref:`arista.eos.eos_config <ansible_collections.arista.eos.eos_config_module>`
+   :ref:`community.kubernetes.kubectl connection plugin <ansible_collections.community.kubernetes.kubectl_connection>`
+
+.. note::
+
+	``ansible.builtin`` is the FQCN for modules included in ``ansible.base``. Documentation links are the only place you prepend ``ansible_collections`` to the FQCN. This is used by the documentation build scripts to correctly fetch documentation from collections on Ansible Galaxy.
 
 .. _local_toc: