update DOCUMENTATION for network_cli and netconf (#33396)

* update DOCUMENTATION for network_cli and netconf

This updates the DOCUMENTATION string for both the netconf and
network_cli connection plugin.

* add additional options to the connection documentation

* update documentation based on review and feedback

* adds persistent connection options to documentation string

lib/ansible/plugins/connection/netconf.py

@@ -5,68 +5,128 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+
 DOCUMENTATION = """
-    author: Ansible Networking Team
-    connection: netconf
-    short_description: Use netconf to run command on network appliances
+---
+author: Ansible Networking Team
+connection: netconf
+short_description: Provides a persistent connection using the netconf protocol
+description:
+  - This connection plugin provides a connection to remote devices over the
+    SSH NETCONF subsystem.  This connection plugin is typically used by
+    network devices for sending and receiving RPC calls over NETCONF.
+  - Note this connection plugin requires ncclient to be installed on the
+    local Ansible controller.
+version_added: "2.3"
+requirements:
+  - ncclient
+options:
+  host:
     description:
-        - Use netconf to run command on network appliances
-    version_added: "2.3"
-    options:
-      network_os:
-        description:
-            - Appliance specific OS
-        default: 'default'
-        vars:
-            - name: ansible_netconf_network_os
-      password:
-        description:
-            - Secret used to authenticate
-        vars:
-            - name: ansible_pass
-            - name: ansible_netconf_pass
-      private_key_file:
-        description:
-            - Key or certificate file used for authentication
-        vars:
-            - name: ansible_private_key_file
-            - name: ansible_netconf_private_key_file
-      ssh_config:
-        type: boolean
-        default: False
-        description:
-            - Flag to decide if we use SSH configuration options with netconf
-        vars:
-            - name: ansible_netconf_ssh_config
-        env:
-            - name: ANSIBLE_NETCONF_SSH_CONFIG
-      user:
-        description:
-          - User to authenticate as
-        vars:
-          - name: ansible_user
-          - name: ansible_netconf_user
-      port:
-        type: int
-        description:
-          - port to connect to on the remote
-        default: 830
-        vars:
-          - name: ansible_port
-          - name: ansible_netconf_port
-      timeout:
-        type: int
-        description:
-          - Connection timeout in seconds
-        default: 120
-      host_key_checking:
-        type: boolean
-        description:
-          - Flag to control wether we check for validity of the host key of the remote
-        default: True
-# TODO:
-#look_for_keys=C.PARAMIKO_LOOK_FOR_KEYS,
-#allow_agent=self.allow_agent,
+      - Specifies the remote device FQDN or IP address to establish the SSH
+        connection to.
+    default: inventory_hostname
+    vars:
+      - name: ansible_host
+  port:
+    type: int
+    description:
+      - Specifies the port on the remote device to listening for connections
+        when establishing the SSH connection.
+    default: 830
+    ini:
+      - section: defaults
+        key: remote_port
+    env:
+      - name: ANSIBLE_REMOTE_PORT
+    vars:
+      - name: ansible_port
+  network_os:
+    description:
+      - Configures the device platform network operating system.  This value is
+        used to load a device specific netconf plugin.  If this option is not
+        configured, then the default netconf plugin will be used.
+    default: null
+    vars:
+      - name: ansible_network_os
+  remote_user:
+    description:
+      - The username used to authenticate to the remote device when the SSH
+        connection is first established.  If the remote_user is not specified,
+        the connection will use the username of the logged in user.
+      - Can be configured form the CLI via the C(--user) or C(-u) options
+    ini:
+      - section: defaults
+        key: remote_user
+    env:
+      - name: ANSIBLE_REMOTE_USER
+    vars:
+      - name: ansible_user
+  password:
+    description:
+      - Configures the user password used to authenticate to the remote device
+        when first establishing the SSH connection.
+    vars:
+      - name: ansible_pass
+  private_key_file:
+    description:
+      - The private SSH key or certificate file used to to authenticate to the
+        remote device when first establishing the SSH connection.
+    ini:
+     section: defaults
+     key: private_key_file
+    env:
+      - name: ANSIBLE_PRIVATE_KEY_FILE
+    vars:
+      - name: ansible_private_key_file
+  timeout:
+    type: int
+    description:
+      - Sets the connection time for the communicating with the remote device.
+        This timeout is used as the default timeout value when awaiting a
+        response after issuing a call to a RPC.  If the RPC does not return in
+        timeout seconds, an error is generated.
+    default: 120
+  host_key_auto_add:
+    type: boolean
+    description:
+      - By default, Ansible will prompt the user before adding SSH keys to the
+        known hosts file.  Enabling this option, unknown host keys will
+        automatically be added to the known hosts file.
+      - Be sure to fully understand the security implications of enabling this
+        option on production systems as it could create a security vulnerability.
+    default: False
+    ini:
+      section: paramiko_connection
+      key: host_key_auto_add
+    env:
+      - name: ANSIBLE_HOST_KEY_AUTO_ADD
+  persistent_connect_timeout:
+    type: int
+    description:
+      - Configures, in seconds, the amount of time to wait when trying to
+        initially establish a persistent connection.  If this value expires
+        before the connection to the remote device is completed, the connection
+        will fail
+    default: 30
+    ini:
+      section: persistent_connection
+      key: persistent_connect_timeout
+    env:
+      - name: ANSIBLE_PERSISTENT_CONNECT_TIMEOUT
+  persistent_command_timeout:
+    type: int
+    description:
+      - Configures, in seconds, the amount of time to wait for a command to
+        return from the remote device.  If this timer is exceeded before the
+        command returns, the connection plugin will raise an exception and
+        close
+    default: 10
+    ini:
+      section: persistent_connection
+      key: persistent_command_timeout
+    env:
+      - name: ANSIBLE_PERSISTENT_COMMAND_TIMEOUT
 """
 
 import os