revises network portion of 2.5 porting guide (#37938)

* revises network portion of 2.5 porting guide

docs/docsite/rst/porting_guides/porting_guide_2.5.rst

@@ -199,12 +199,21 @@ Porting custom scripts
 
 No notable changes.
 
-Networking
+Network
-==========
+=======
 
+Expanding documentation
+-----------------------
+
+We're expanding the network documentation. There's new content and a :ref:`new Ansible Network landing page<network_guide>`. We will continue to build the network-related documentation moving forward.
+
+Top-level connection arguments will be removed in 2.9
+-----------------------------------------------------
+
+Top-level connection arguments like ``username``, ``host``, and ``password`` are deprecated and will be removed in version 2.9.
+
+**OLD** In Ansible < 2.4
 
-Change in deprecation notice of top-level connection arguments
---------------------------------------------------------------
 .. code-block:: yaml
 
     - name: example of using top-level options for connection properties
@@ -216,19 +225,7 @@ Change in deprecation notice of top-level connection arguments
         authorize: yes
         auth_pass: cisco
 
-**OLD** In Ansible 2.4:
+The deprecation warnings reflect this schedule. The task above, run in Ansible 2.5, will result in:
-
-Will result in:
-
-.. code-block:: yaml
-
-   [WARNING]: argument username has been deprecated and will be removed in a future version
-   [WARNING]: argument host has been deprecated and will be removed in a future version
-   [WARNING]: argument password has been deprecated and will be removed in a future version
-
-
-**NEW** In Ansible 2.5:
-
 
 .. code-block:: yaml
 
@@ -239,13 +236,51 @@ Will result in:
    [DEPRECATION WARNING]: Param 'host' is deprecated. See the module docs for more information. This feature will be removed in version 2.9.
    Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg.
 
-Notice when using provider dictionary with new persistent connection types
+We recommend using the new connection types ``network_cli`` and ``netconf`` (see below), using standard Ansible connection properties, and setting those properties in inventory by group. As you update your playbooks and inventory files, you can easily make the change to ``become`` for privilege escalation (on platforms that support it). For more information, see the :ref:`using become with network modules<become-network>` guide and the :ref:`platform documentation<platform_options>`.
---------------------------------------------------------------------------
+
+Adding persistent connection types ``network_cli`` and ``netconf``
+------------------------------------------------------------------
+
+Ansible 2.5 introduces two top-level persistent connection types, ``network_cli`` and ``netconf``. With ``connection: local``, each task passed the connection parameters, which had to be stored in your playbooks. With ``network_cli`` and ``netconf`` the playbook passes the connection parameters once, so you can pass them at the command line if you prefer. We recommend you use ``network_cli`` and ``netconf`` whenever possible.
+Note that eAPI and NX-API still require ``local`` connections with ``provider`` dictionaries. See the :ref:`platform documentation<platform_options>` for more information. Unless you need a ``local`` connection, update your playbooks to use ``network_cli`` or ``netconf`` and to specify your connection variables with standard Ansible connection variables:
+
+**OLD** In Ansible 2.4
+
+.. code-block:: yaml
+
+   ---
+   vars:
+       cli:
+          host: "{{ inventory_hostname }}"
+          username: operator
+          password: secret
+          transport: cli
+
+   tasks:
+   - nxos_config:
+       src: config.j2
+       provider: "{{ cli }}"
+       username: admin
+       password: admin
+
+**NEW** In Ansible 2.5
+
+.. code-block:: ini
+
+   [nxos:vars]
+   ansible_connection=network_cli
+   ansible_network_os=nxos
+   ansible_user=operator
+   ansible_password=secret
+
+.. code-block:: yaml
+
+   tasks:
+   - nxos_config:
+       src: config.j2
+
+Using a provider dictionary with either ``network_cli`` or ``netconf`` will result in a warning.
 
-Using a provider dictionary with one of the new persistent connection types for networking
-(network_cli, netconf, etc.) will result in a warning. When using these connections
-the standard Ansible infrastructure for controlling connections should be used.
-(Link to basic inventory documentation?)
 
 Developers: Shared Module Utilities Moved
 -----------------------------------------
@@ -258,13 +293,13 @@ Beginning with Ansible 2.5, shared module utilities for network modules moved to
 
 If your module uses shared module utilities, you must update all references. For example, change:
 
-OLD In Ansible 2.4
+**OLD** In Ansible 2.4
 
 .. code-block:: python
 
    from ansible.module_utils.vyos import get_config, load_config
 
-NEW In Ansible 2.5
+**NEW** In Ansible 2.5
 
 .. code-block:: python