Add anchors to some guides and all module categories (#36642)

* Add anchors to some guides and all module categories

This is required if we want to use *absolute* :ref: references instead of *relative* :doc: references.

* Update the Cisco ACI Guide reference

* Add `aci_guide` anchor

* Add `network_guide` anchor

* Add category anchor

* Improve readability

* Fix small typo

docs/docsite/rst/network/index.rst

@@ -1,3 +1,5 @@
+.. _network_guide:
+
 ******************************
 Ansible for Network Automation
 ******************************

docs/docsite/rst/scenario_guides/guide_aci.rst

@@ -1,3 +1,5 @@
+.. _aci_guide:
+
 Cisco ACI Guide
 ===============
 
@@ -100,7 +102,7 @@ Every Ansible ACI module accepts the following parameters that influence the mod
 
 Proxy support
 .............
-By default, if an environment variable ``<protocol>_proxy`` is set on the target host, requests will be sent through that proxy. This behaviour can be overridden by setting a variable for this task (see :ref:`setting the environment <playbooks_environment>`), or by using the ``use_proxy`` module parameter.
+By default, if an environment variable ``<protocol>_proxy`` is set on the target host, requests will be sent through that proxy. This behaviour can be overridden by setting a variable for this task (see :ref:`playbooks_environment`), or by using the ``use_proxy`` module parameter.
 
 HTTP redirects can redirect from HTTP to HTTPS so you should be sure that your proxy environment for both protocols is correct.
 
@@ -176,7 +178,7 @@ Password-based authentication is very simple to work with, but it is not the mos
 
 .. warning:: Never store passwords in plain text.
 
-The "Vault" feature of Ansible allows you to keep sensitive data such as passwords or keys in encrypted files, rather than as plain text in your playbooks or roles. These vault files can then be distributed or placed in source control. See :doc:`playbooks_vault` for more information.
+The "Vault" feature of Ansible allows you to keep sensitive data such as passwords or keys in encrypted files, rather than as plain text in your playbooks or roles. These vault files can then be distributed or placed in source control. See :ref:`playbooks_vault` for more information.
 
 
 Signature-based authentication using certificates
@@ -240,7 +242,7 @@ You need the following parameters with your ACI module(s) for it to work:
 
 More information
 ,,,,,,,,,,,,,,,,
-More information about Signature-based Authentication is available from `Cisco APIC Signature-Based Transactions <https://www.cisco.com/c/en/us/td/docs/switches/datacenter/aci/apic/sw/kb/b_KB_Signature_Based_Transactions.html>`_.
+Detailed information about Signature-based Authentication is available from `Cisco APIC Signature-Based Transactions <https://www.cisco.com/c/en/us/td/docs/switches/datacenter/aci/apic/sw/kb/b_KB_Signature_Based_Transactions.html>`_.
 
 
 .. _aci_guide_rest:
@@ -438,3 +440,19 @@ ACI Ansible community
 If you have specific issues with the ACI modules, or a feature request, or you like to contribute to the ACI project by proposing changes or documentation updates, look at the Ansible Community wiki ACI page at: https://github.com/ansible/community/wiki/Network:-ACI
 
 You will find our roadmap, an overview of open ACI issues and pull-requests and more information about who we are. If you have an interest in using ACI with Ansible, feel free to join ! We occasionally meet online to track progress and prepare for new Ansible releases.
+
+
+.. seealso::
+
+   :ref:`network_guide`
+       Ansible for Network Automation
+   :ref:`List of ACI modules <aci_network_modules>`
+       A complete list of supported ACI modules
+   `ACI community <https://github.com/ansible/community/wiki/Network:-ACI>`_
+       The Ansible ACI community wiki page, includes roadmap, ideas and development documentation
+   `Network Working Group <https://github.com/ansible/community/tree/master/group-network>`_
+       The Ansible Network community page, includes contact information and meeting information
+   `User Mailing List <http://groups.google.com/group/ansible-project>`_
+       Have a question?  Stop by the google group!
+   `#ansible-network <https://webchat.freenode.net/?channels=ansible-network>`_
+       The #ansible-network IRC chat channel on Freenode.net

docs/docsite/rst/user_guide/playbooks_environment.rst

@@ -1,3 +1,5 @@
+.. _playbooks_environment:
+
 Setting the Environment (and Working With Proxies)
 ==================================================
 

docs/docsite/rst/user_guide/playbooks_vault.rst

@@ -1,3 +1,5 @@
+.. _playbooks_vault:
+
 Using Vault in playbooks
 ========================
 

docs/templates/list_of_CATEGORY_modules.rst.j2

@@ -1,3 +1,5 @@
+.. _@{ title.lower() + '_' + plugin_type + 's' }@:
+
 @{ title }@ @{ plugin_type + 's' }@
 @{ '`' * title | length }@````````
 
@@ -14,6 +16,9 @@
 {% endif %}
 
 {% for name, info in subcategories.items() | sort %}
+
+.. _@{ name.lower() + '_' + title.lower() + '_' + plugin_type + 's' }@:
+
 @{ name.title() }@
 @{ '-' * name | length }@
 

docs/templates/list_of_CATEGORY_plugins.rst.j2

@@ -1,3 +1,5 @@
+.. _@{ title.lower() + '_' + plugin_type + 's' }@:
+
 @{ title }@ @{ plugin_type }@
 @{ '`' * title | length }@````````
 
@@ -14,6 +16,9 @@
 {% endif %}
 
 {% for name, info in subcategories.items() | sort %}
+
+.. _@{ name.lower() + '_' + title.lower() + '_' + plugin_type + 's' }@:
+
 @{ name.title() }@
 @{ '-' * name | length }@
 

lib/ansible/utils/module_docs_fragments/aci.py

@@ -3,20 +3,7 @@
 # Copyright: (c) 2017, Dag Wieers (@dagwieers) <dag@wieers.com>
 # Copyright: (c) 2017, Swetha Chunduri (@schunduri)
 
-# This file is part of Ansible by Red Hat
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 
 class ModuleDocFragment(object):
@@ -31,8 +18,8 @@ options:
   port:
     description:
     - Port number to be used for REST connection.
-    default: 443 (for https) and 80 (for http)
     type: int
+    default: 443 (for https) and 80 (for http)
   username:
     description:
     - The username to use for authentication.
@@ -52,8 +39,8 @@ options:
     description:
     - The X.509 certificate name attached to the APIC AAA user used for signature-based authentication.
     - It defaults to the C(private_key) basename, without extension.
-    aliases: [ cert_name ]
     default: C(private_key) basename
+    aliases: [ cert_name ]
   output_level:
     description:
     - Influence the output of this ACI module.
@@ -65,6 +52,7 @@ options:
   timeout:
     description:
     - The socket level timeout in seconds.
+    type: int
     default: 30
   use_proxy:
     description:
@@ -83,6 +71,5 @@ options:
     type: bool
     default: 'yes'
 notes:
-- Please read :ref:`the ACI guide <aci_guide>` for more detailed information
+- Please read the :ref:`aci_guide` for more detailed information on how to manage your ACI infrastructure using Ansible.
-  on how to manage your ACI infrastructure using Ansible.
 '''