Network modules to link to network guide (#37033) (#37069)

* Network modules to link to network guide

* Make it clear what's deprecated
* enable -> become
* Detail when provider is still needed (eAPI/NX-API)
* Link to specific sections
* rx_rate & tx_rate to link to conditional docs

(cherry picked from commit ebc71bcb1635af43b05438839157aea9ab65ae71)

14 files changed, 97 insertions, 8 deletions

diff --git a/lib/ansible/modules/network/eos/eos_interface.py b/lib/ansible/modules/network/eos/eos_interface.py
index 500540bd64..8f86b8502f 100644
--- a/lib/ansible/modules/network/eos/eos_interface.py
+++ b/lib/ansible/modules/network/eos/eos_interface.py
@@ -49,9 +49,13 @@ options:
   tx_rate:
     description:
       - Transmit rate in bits per second (bps) for the interface given in C(name) option.
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
   rx_rate:
     description:
       - Receiver rate in bits per second (bps) for the interface given in C(name) option.
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
   neighbors:
     description:
       - Check the operational state of given interface C(name) for LLDP neighbor.
diff --git a/lib/ansible/modules/network/interface/net_interface.py b/lib/ansible/modules/network/interface/net_interface.py
index 7033030319..89d6f12876 100644
--- a/lib/ansible/modules/network/interface/net_interface.py
+++ b/lib/ansible/modules/network/interface/net_interface.py
@@ -47,9 +47,13 @@ options:
   tx_rate:
     description:
       - Transmit rate in bits per second (bps).
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
   rx_rate:
     description:
       - Receiver rate in bits per second (bps).
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
   delay:
     description:
       - Time in seconds to wait before checking for the operational state on remote
diff --git a/lib/ansible/modules/network/ios/ios_interface.py b/lib/ansible/modules/network/ios/ios_interface.py
index 1af44f489b..56d6c7db6c 100644
--- a/lib/ansible/modules/network/ios/ios_interface.py
+++ b/lib/ansible/modules/network/ios/ios_interface.py
@@ -49,9 +49,13 @@ options:
   tx_rate:
     description:
       - Transmit rate in bits per second (bps).
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
   rx_rate:
     description:
       - Receiver rate in bits per second (bps).
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
   neighbors:
     description:
       - Check the operational state of given interface C(name) for LLDP neighbor.
diff --git a/lib/ansible/modules/network/iosxr/iosxr_interface.py b/lib/ansible/modules/network/iosxr/iosxr_interface.py
index 4fdcae00b9..59b3dafd4a 100644
--- a/lib/ansible/modules/network/iosxr/iosxr_interface.py
+++ b/lib/ansible/modules/network/iosxr/iosxr_interface.py
@@ -64,9 +64,13 @@ options:
   tx_rate:
     description:
       - Transmit rate in bits per second (bps).
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
   rx_rate:
     description:
       - Receiver rate in bits per second (bps).
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
   aggregate:
     description:
       - List of Interface definitions. Include multiple interface configurations together,
diff --git a/lib/ansible/modules/network/junos/junos_interface.py b/lib/ansible/modules/network/junos/junos_interface.py
index 7baa46a700..b63b8e9d1b 100644
--- a/lib/ansible/modules/network/junos/junos_interface.py
+++ b/lib/ansible/modules/network/junos/junos_interface.py
@@ -47,9 +47,13 @@ options:
   tx_rate:
     description:
       - Transmit rate in bits per second (bps).
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
   rx_rate:
     description:
       - Receiver rate in bits per second (bps).
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
   neighbors:
     description:
       - Check the operational state of given interface C(name) for LLDP neighbor.
diff --git a/lib/ansible/modules/network/nxos/nxos_interface.py b/lib/ansible/modules/network/nxos/nxos_interface.py
index db408768f4..d68d3730a4 100644
--- a/lib/ansible/modules/network/nxos/nxos_interface.py
+++ b/lib/ansible/modules/network/nxos/nxos_interface.py
@@ -107,12 +107,14 @@ options:
   tx_rate:
     description:
       - Transmit rate in bits per second (bps).
-        This is state check parameter only.
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
     version_added: 2.5
   rx_rate:
     description:
       - Receiver rate in bits per second (bps).
-        This is state check parameter only.
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
     version_added: 2.5
   neighbors:
     description:
diff --git a/lib/ansible/modules/network/onyx/onyx_interface.py b/lib/ansible/modules/network/onyx/onyx_interface.py
index 9e1c189fde..2b39b16a1a 100644
--- a/lib/ansible/modules/network/onyx/onyx_interface.py
+++ b/lib/ansible/modules/network/onyx/onyx_interface.py
@@ -49,9 +49,13 @@ options:
   tx_rate:
     description:
       - Transmit rate in bits per second (bps).
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
   rx_rate:
     description:
       - Receiver rate in bits per second (bps).
+      - This is state check parameter only.
+      - Supports conditionals, see L(Conditionals in Networking Modules,../network/user_guide/network_working_with_command_output.html)
   delay:
     description:
       - Time in seconds to wait before checking for the operational state on
diff --git a/lib/ansible/utils/module_docs_fragments/asa.py b/lib/ansible/utils/module_docs_fragments/asa.py
index e8908595c6..68f4b1a49c 100644
--- a/lib/ansible/utils/module_docs_fragments/asa.py
+++ b/lib/ansible/utils/module_docs_fragments/asa.py
@@ -25,6 +25,10 @@ class ModuleDocFragment(object):
 options:
   authorize:
     description:
+      - B(Deprecated)
+      - "Starting with Ansible 2.5 we recommend using C(connection: network_cli) and C(become: yes)."
+      - For more information please see the L(Network Guide, ../network/getting_started/network_differences.html#multiple-communication-protocols).
+      - HORIZONTALLINE
       - Instructs the module to enter privileged mode on the remote device
         before sending any commands.  If not specified, the device will
         attempt to execute all commands in non-privileged mode. If the value
@@ -39,6 +43,10 @@ options:
     default: null
   provider:
     description:
+      - B(Deprecated)
+      - "Starting with Ansible 2.5 we recommend using C(connection: network_cli)."
+      - For more information please see the L(Network Guide, ../network/getting_started/network_differences.html#multiple-communication-protocols).
+      - HORIZONTALLINE
       - A dict object containing connection details.
     default: null
     suboptions:
@@ -94,4 +102,6 @@ options:
             if the console freezes before continuing. For example when saving
             configurations.
         default: 10
+notes:
+  - For more information on using Ansible to manage network devices see the :ref:`Ansible Network Guide <network_guide>`
 """
diff --git a/lib/ansible/utils/module_docs_fragments/eos.py b/lib/ansible/utils/module_docs_fragments/eos.py
index 872f55f448..e1a338d9d7 100644
--- a/lib/ansible/utils/module_docs_fragments/eos.py
+++ b/lib/ansible/utils/module_docs_fragments/eos.py
@@ -24,6 +24,11 @@ class ModuleDocFragment(object):
 options:
   authorize:
     description:
+      - B(Deprecated)
+      - "Starting with Ansible 2.5 we recommend using C(connection: network_cli) and C(become: yes)."
+      - This option is only required if you are using eAPI.
+      - For more information please see the L(EOS Platform Options guide, ../network/user_guide/platform_eos.html).
+      - HORIZONTALLINE
       - Instructs the module to enter privileged mode on the remote device
         before sending any commands.  If not specified, the device will
         attempt to execute all commands in non-privileged mode. If the value
@@ -33,6 +38,11 @@ options:
     choices: ['yes', 'no']
   auth_pass:
     description:
+      - B(Deprecated)
+      - "Starting with Ansible 2.5 we recommend using C(connection: network_cli) and C(become: yes) with C(become_pass)."
+      - This option is only required if you are using eAPI.
+      - For more information please see the L(EOS Platform Options guide, ../network/user_guide/platform_eos.html).
+      - HORIZONTALLINE
       - Specifies the password to use if required to enter privileged mode
         on the remote device.  If I(authorize) is false, then this argument
         does nothing. If the value is not specified in the task, the value of
@@ -40,6 +50,11 @@ options:
     default: none
   provider:
     description:
+      - B(Deprecated)
+      - "Starting with Ansible 2.5 we recommend using C(connection: network_cli)."
+      - This option is only required if you are using eAPI.
+      - For more information please see the L(EOS Platform Options guide, ../network/user_guide/platform_eos.html).
+      - HORIZONTALLINE
       - A dict object containing connection details.
     default: null
     suboptions:
@@ -128,6 +143,8 @@ options:
         version_added: "2.5"
 
 notes:
-  - For more information on using Ansible to manage Arista EOS devices see U(https://www.ansible.com/ansible-arista-networks).
+  - For information on using CLI, eAPI and privileged mode see the :ref:`EOS Platform Options guide <eos_platform_options>`
+  - For more information on using Ansible to manage network devices see the :ref:`Ansible Network Guide <network_guide>`
+  - For more information on using Ansible to manage Arista EOS devices see the `Arista integration page <https://www.ansible.com/ansible-arista-networks>`_.
 
 """
diff --git a/lib/ansible/utils/module_docs_fragments/ios.py b/lib/ansible/utils/module_docs_fragments/ios.py
index 34621ce24b..225e0ccd03 100644
--- a/lib/ansible/utils/module_docs_fragments/ios.py
+++ b/lib/ansible/utils/module_docs_fragments/ios.py
@@ -24,6 +24,10 @@ class ModuleDocFragment(object):
 options:
   authorize:
     description:
+      - B(Deprecated)
+      - "Starting with Ansible 2.5 we recommend using C(connection: network_cli) and C(become: yes)."
+      - For more information please see the L(IOS Platform Options guide, ../network/user_guide/platform_ios.html).
+      - HORIZONTALLINE
       - Instructs the module to enter privileged mode on the remote device
         before sending any commands.  If not specified, the device will
         attempt to execute all commands in non-privileged mode. If the value
@@ -33,6 +37,10 @@ options:
     choices: ['yes', 'no']
   auth_pass:
     description:
+      - B(Deprecated)
+      - "Starting with Ansible 2.5 we recommend using C(connection: network_cli) and C(become: yes) with C(become_pass)."
+      - For more information please see the L(IOS Platform Options guide, ../network/user_guide/platform_ios.html).
+      - HORIZONTALLINE
       - Specifies the password to use if required to enter privileged mode
         on the remote device.  If I(authorize) is false, then this argument
         does nothing. If the value is not specified in the task, the value of
@@ -40,6 +48,10 @@ options:
     default: none
   provider:
     description:
+      - B(Deprecated)
+      - "Starting with Ansible 2.5 we recommend using C(connection: network_cli)."
+      - For more information please see the L(IOS Platform Options guide, ../network/user_guide/platform_ios.html).
+      - HORIZONTALLINE
       - A dict object containing connection details.
     default: null
     suboptions:
@@ -96,5 +108,6 @@ options:
             environment variable C(ANSIBLE_NET_AUTH_PASS) will be used instead.
         default: none
 notes:
-  - For more information on using Ansible to manage Cisco devices see U(https://www.ansible.com/ansible-cisco).
+  - For more information on using Ansible to manage network devices see the :ref:`Ansible Network Guide <network_guide>`
+  - For more information on using Ansible to manage Cisco devices see the `Cisco integration page <https://www.ansible.com/integrations/networks/cisco>`_.
 """
diff --git a/lib/ansible/utils/module_docs_fragments/iosxr.py b/lib/ansible/utils/module_docs_fragments/iosxr.py
index 775c9e3b3c..ce1ff18164 100644
--- a/lib/ansible/utils/module_docs_fragments/iosxr.py
+++ b/lib/ansible/utils/module_docs_fragments/iosxr.py
@@ -24,6 +24,10 @@ class ModuleDocFragment(object):
 options:
   provider:
     description:
+      - B(Deprecated)
+      - "Starting with Ansible 2.5 we recommend using C(connection: network_cli)."
+      - For more information please see the L(Network Guide, ../network/getting_started/network_differences.html#multiple-communication-protocols).
+      - HORIZONTALLINE
       - A dict object containing connection details.
     default: null
     suboptions:
@@ -35,8 +39,7 @@ options:
         required: true
       port:
         description:
-          - Specifies the port to use when building the connection to the remote.
-            device.
+          - Specifies the port to use when building the connection to the remote device.
         default: 22
       username:
         description:
@@ -68,5 +71,6 @@ requirements:
     - "ncclient >= 0.5.3 when using netconf"
     - "lxml >= 4.1.1 when using netconf"
 notes:
-  - For more information on using Ansible to manage Cisco devices see U(https://www.ansible.com/ansible-cisco).
+  - For more information on using Ansible to manage network devices see the :ref:`Ansible Network Guide <network_guide>`
+  - For more information on using Ansible to manage Cisco devices see the `Cisco integration page <https://www.ansible.com/integrations/networks/cisco>`_.
 """
diff --git a/lib/ansible/utils/module_docs_fragments/junos.py b/lib/ansible/utils/module_docs_fragments/junos.py
index 21f0ffb548..03e22ac6a6 100644
--- a/lib/ansible/utils/module_docs_fragments/junos.py
+++ b/lib/ansible/utils/module_docs_fragments/junos.py
@@ -24,6 +24,10 @@ class ModuleDocFragment(object):
 options:
   provider:
     description:
+      - B(Deprecated)
+      - "Starting with Ansible 2.5 we recommend using C(connection: network_cli) or C(connection: netconf)."
+      - For more information please see the L(Junos OS Platform Options guide, ../network/user_guide/platform_junos.html).
+      - HORIZONTALLINE
       - A dict object containing connection details.
     default: null
     suboptions:
@@ -67,5 +71,7 @@ options:
             the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE)
             will be used instead.
 notes:
+  - For information on using CLI and netconf see the :ref:`Junos OS Platform Options guide <junos_platform_options>`
+  - For more information on using Ansible to manage network devices see the :ref:`Ansible Network Guide <network_guide>`
   - For more information on using Ansible to manage Juniper network devices see U(https://www.ansible.com/ansible-juniper).
 """
diff --git a/lib/ansible/utils/module_docs_fragments/nxos.py b/lib/ansible/utils/module_docs_fragments/nxos.py
index 389ed298d8..44804c5505 100644
--- a/lib/ansible/utils/module_docs_fragments/nxos.py
+++ b/lib/ansible/utils/module_docs_fragments/nxos.py
@@ -24,6 +24,11 @@ class ModuleDocFragment(object):
 options:
   provider:
     description:
+      - B(Deprecated)
+      - "Starting with Ansible 2.5 we recommend using C(connection: network_cli)."
+      - This option is only required if you are using NX-API.
+      - For more information please see the L(NXOS Platform Options guide, ../network/user_guide/platform_nxos.html).
+      - HORIZONTALLINE
       - A dict object containing connection details.
     default: null
     suboptions:
@@ -102,5 +107,7 @@ options:
         version_added: "2.5"
 
 notes:
-  - For more information on using Ansible to manage Cisco devices see U(https://www.ansible.com/ansible-cisco).
+  - For information on using CLI and NX-API see the :ref:`NXOS Platform Options guide <nxos_platform_options>`
+  - For more information on using Ansible to manage network devices see the :ref:`Ansible Network Guide <network_guide>`
+  - For more information on using Ansible to manage Cisco devices see the `Cisco integration page <https://www.ansible.com/integrations/networks/cisco>`_.
 """
diff --git a/lib/ansible/utils/module_docs_fragments/vyos.py b/lib/ansible/utils/module_docs_fragments/vyos.py
index 45ad3d9105..dd8dadd94e 100644
--- a/lib/ansible/utils/module_docs_fragments/vyos.py
+++ b/lib/ansible/utils/module_docs_fragments/vyos.py
@@ -24,6 +24,10 @@ class ModuleDocFragment(object):
 options:
   provider:
     description:
+      - B(Deprecated)
+      - "Starting with Ansible 2.5 we recommend using C(connection: network_cli)."
+      - For more information please see the L(Network Guide, ../network/getting_started/network_differences.html#multiple-communication-protocols).
+      - HORIZONTALLINE
       - A dict object containing connection details.
     default: null
     suboptions:
@@ -64,4 +68,6 @@ options:
             key used to authenticate the SSH session. If the value is not specified
             in the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE)
             will be used instead.
+notes:
+  - For more information on using Ansible to manage network devices see the :ref:`Ansible Network Guide <network_guide>`
 """