Document httpapi and cliconf plugins (#49503)

* Create new documentation pages for httpapi and cliconf

* Add new documentation to plugins toctree and Makefile

* Add DOCUMENTATION to cliconf

* Apply suggestions from code review

30 files changed, 359 insertions, 7 deletions

diff --git a/docs/docsite/Makefile b/docs/docsite/Makefile
index 97a07af104..c97936bc70 100644
--- a/docs/docsite/Makefile
+++ b/docs/docsite/Makefile
@@ -26,7 +26,7 @@ ifdef PLUGINS
 	PLUGIN_ARGS = -l $(PLUGINS)
 endif
 
-DOC_PLUGINS ?= cache callback connection inventory lookup shell strategy vars
+DOC_PLUGINS ?= cache callback cliconf connection httpapi inventory lookup shell strategy vars
 
 assertrst:
 ifndef rst
diff --git a/docs/docsite/rst/plugins/cliconf.rst b/docs/docsite/rst/plugins/cliconf.rst
new file mode 100644
index 0000000000..f6b83d80d6
--- /dev/null
+++ b/docs/docsite/rst/plugins/cliconf.rst
@@ -0,0 +1,57 @@
+.. _cliconf_plugins:
+
+Cliconf Plugins
+===============
+
+.. contents::
+   :local:
+   :depth: 2
+
+Cliconf plugins are abstactions over the CLI interface to network devices. They provide a standard interface
+for Ansible to execute tasks on those network devices.
+
+These plugins generally correspond one-to-one to network device platforms. The appropriate cliconf plugin will
+thus be automatically loaded based on the ``ansible_network_os`` variable.
+
+.. _enabling_cliconf:
+
+Adding cliconf plugins
+-------------------------
+
+You can extend Ansible to support other network devices by dropping a custom plugin into the ``cliconf_plugins`` directory.
+
+.. _using_cliconf:
+
+Using cliconf plugins
+------------------------
+
+The cliconf plugin to use is determined automatically from the ``ansible_network_os`` variable. There should be no reason to override this functionality.
+
+Most cliconf plugins can operate without configuration. A few have additional options that can be set to impact how
+tasks are translated into CLI commands.
+
+Plugins are self-documenting. Each plugin should document its configuration options.
+
+.. _cliconf_plugin_list:
+
+Plugin list
+-----------
+
+You can use ``ansible-doc -t cliconf -l`` to see the list of available plugins.
+Use ``ansible-doc -t cliconf <plugin name>`` to see detailed documentation and examples.
+
+
+.. toctree:: :maxdepth: 1
+    :glob:
+
+    cliconf/*
+
+
+.. seealso::
+
+   :ref:`Ansible for Network Automation<network_guide>`
+       An overview of using Ansible to automate networking devices.
+   `User Mailing List <https://groups.google.com/group/ansible-devel>`_
+       Have a question?  Stop by the google group!
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible-network IRC chat channel
diff --git a/docs/docsite/rst/plugins/httpapi.rst b/docs/docsite/rst/plugins/httpapi.rst
new file mode 100644
index 0000000000..bd93412802
--- /dev/null
+++ b/docs/docsite/rst/plugins/httpapi.rst
@@ -0,0 +1,57 @@
+.. _httpapi_plugins:
+
+Httpapi Plugins
+===============
+
+.. contents::
+   :local:
+   :depth: 2
+
+Httpapi plugins tell Ansible how to interact with a remote device's HTTP-based API and execute tasks on the
+device.
+
+Each plugin represents a particular dialect of API. Some are platform-specific (Arista eAPI, Cisco NXAPI), while
+others might be usable on a variety of platforms (RESTCONF).
+
+.. _enabling_httpapi:
+
+Adding httpapi plugins
+-------------------------
+
+You can extend Ansible to support other APIs by dropping a custom plugin into the ``httpapi_plugins`` directory.
+
+.. _using_httpapi:
+
+Using httpapi plugins
+------------------------
+
+The httpapi plugin to use is determined automatically from the ``ansible_network_os`` variable.
+
+Most httpapi plugins can operate without configuration. Additional options may be defined by each plugin.
+
+Plugins are self-documenting. Each plugin should document its configuration options.
+
+
+.. _httpapi_plugin_list:
+
+Plugin List
+-----------
+
+You can use ``ansible-doc -t httpapi -l`` to see the list of available plugins.
+Use ``ansible-doc -t httpapi <plugin name>`` to see detailed documentation and examples.
+
+
+.. toctree:: :maxdepth: 1
+    :glob:
+
+    httpapi/*
+
+
+.. seealso::
+
+   :ref:`Ansible for Network Automation<network_guide>`
+       An overview of using Ansible to automate networking devices.
+   `User Mailing List <https://groups.google.com/group/ansible-devel>`_
+       Have a question?  Stop by the google group!
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible-network IRC chat channel
diff --git a/docs/docsite/rst/plugins/plugins.rst b/docs/docsite/rst/plugins/plugins.rst
index 2a7d3c2fea..fc55d93a92 100644
--- a/docs/docsite/rst/plugins/plugins.rst
+++ b/docs/docsite/rst/plugins/plugins.rst
@@ -16,7 +16,9 @@ This section covers the various types of plugins that are included with Ansible:
    action
    cache
    callback
+   cliconf
    connection
+   httpapi
    inventory
    lookup
    shell
diff --git a/lib/ansible/plugins/cliconf/aireos.py b/lib/ansible/plugins/cliconf/aireos.py
index bad7f50339..453683f449 100644
--- a/lib/ansible/plugins/cliconf/aireos.py
+++ b/lib/ansible/plugins/cliconf/aireos.py
@@ -19,6 +19,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: aireos
+short_description: Use aireos cliconf to run command on Cisco WLC platform
+description:
+  - This aireos plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Cisco WLC network devices.
+version_added: 2.4
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/aruba.py b/lib/ansible/plugins/cliconf/aruba.py
index c8c3045ac7..e8e0674336 100644
--- a/lib/ansible/plugins/cliconf/aruba.py
+++ b/lib/ansible/plugins/cliconf/aruba.py
@@ -19,6 +19,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: aruba
+short_description: Use aruba cliconf to run command on Aruba platform
+description:
+  - This aruba plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Aruba network devices.
+version_added: 2.4
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/asa.py b/lib/ansible/plugins/cliconf/asa.py
index d0d23cad43..2c12fcff30 100644
--- a/lib/ansible/plugins/cliconf/asa.py
+++ b/lib/ansible/plugins/cliconf/asa.py
@@ -19,6 +19,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: asa
+short_description: Use asa cliconf to run command on Cisco ASA platform
+description:
+  - This asa plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Cisco ASA network devices.
+version_added: 2.4
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/ce.py b/lib/ansible/plugins/cliconf/ce.py
index 6790860c8d..d10c30cbc3 100644
--- a/lib/ansible/plugins/cliconf/ce.py
+++ b/lib/ansible/plugins/cliconf/ce.py
@@ -19,6 +19,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: ce
+short_description: Use ce cliconf to run command on HUAWEI CloudEngine platform
+description:
+  - This ce plugin provides low level abstraction apis for
+    sending and receiving CLI commands from HUAWEI CloudEngine network devices.
+version_added: 2.7
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/cnos.py b/lib/ansible/plugins/cliconf/cnos.py
index 187e49f00e..52fa83abd0 100644
--- a/lib/ansible/plugins/cliconf/cnos.py
+++ b/lib/ansible/plugins/cliconf/cnos.py
@@ -16,6 +16,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: cnos
+short_description: Use cnos cliconf to run command on Lenovo CNOS platform
+description:
+  - This cnos plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Lenovo CNOS network devices.
+version_added: 2.6
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/dellos10.py b/lib/ansible/plugins/cliconf/dellos10.py
index 2ed9982bbe..032d463323 100644
--- a/lib/ansible/plugins/cliconf/dellos10.py
+++ b/lib/ansible/plugins/cliconf/dellos10.py
@@ -21,6 +21,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: dellos10
+short_description: Use dellos10 cliconf to run command on Dell OS10 platform
+description:
+  - This dellos10 plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Dell OS10 network devices.
+version_added: 2.5
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/dellos6.py b/lib/ansible/plugins/cliconf/dellos6.py
index 746f253056..8bfe713905 100644
--- a/lib/ansible/plugins/cliconf/dellos6.py
+++ b/lib/ansible/plugins/cliconf/dellos6.py
@@ -21,6 +21,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: dellos6
+short_description: Use dellos6 cliconf to run command on Dell OS6 platform
+description:
+  - This dellos6 plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Dell OS6 network devices.
+version_added: 2.5
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/dellos9.py b/lib/ansible/plugins/cliconf/dellos9.py
index 2ea9d1fdf9..ee72acf1a8 100644
--- a/lib/ansible/plugins/cliconf/dellos9.py
+++ b/lib/ansible/plugins/cliconf/dellos9.py
@@ -21,6 +21,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: dellos9
+short_description: Use dellos9 cliconf to run command on Dell OS9 platform
+description:
+  - This dellos9 plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Dell OS9 network devices.
+version_added: 2.5
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/edgeos.py b/lib/ansible/plugins/cliconf/edgeos.py
index 970de0e33e..af23df9a6a 100644
--- a/lib/ansible/plugins/cliconf/edgeos.py
+++ b/lib/ansible/plugins/cliconf/edgeos.py
@@ -5,6 +5,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: edgeos
+short_description: Use edgeos cliconf to run command on EdgeOS platform
+description:
+  - This edgeos plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Ubiquiti EdgeOS network devices.
+version_added: "2.5"
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/edgeswitch.py b/lib/ansible/plugins/cliconf/edgeswitch.py
index 44903ccbf6..c080a2470b 100644
--- a/lib/ansible/plugins/cliconf/edgeswitch.py
+++ b/lib/ansible/plugins/cliconf/edgeswitch.py
@@ -19,6 +19,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: edgeswitch
+short_description: Use edgeswitch cliconf to run command on EdgeSwitch platform
+description:
+  - This edgeswitch plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Ubiquiti EdgeSwitch network devices.
+version_added: "2.8"
+"""
+
 import re
 import time
 import json
diff --git a/lib/ansible/plugins/cliconf/enos.py b/lib/ansible/plugins/cliconf/enos.py
index 3c9267f3ef..272743f1c5 100644
--- a/lib/ansible/plugins/cliconf/enos.py
+++ b/lib/ansible/plugins/cliconf/enos.py
@@ -16,6 +16,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: enos
+short_description: Use enos cliconf to run command on Lenovo ENOS platform
+description:
+  - This enos plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Lenovo ENOS network devices.
+version_added: "2.5"
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/eos.py b/lib/ansible/plugins/cliconf/eos.py
index d5b1824086..f878a843ec 100644
--- a/lib/ansible/plugins/cliconf/eos.py
+++ b/lib/ansible/plugins/cliconf/eos.py
@@ -23,11 +23,11 @@ DOCUMENTATION = """
 ---
 author: Ansible Networking Team
 cliconf: eos
-short_description: Use eos cliconf to run command on eos platform
+short_description: Use eos cliconf to run command on Arista EOS platform
 description:
-  - This eos plugin provides low level abstraction api's for
-    sending and receiving CLI commands from eos network devices.
-version_added: "2.7"
+  - This eos plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Arista EOS network devices.
+version_added: "2.4"
 options:
   eos_use_sessions:
     type: int
diff --git a/lib/ansible/plugins/cliconf/exos.py b/lib/ansible/plugins/cliconf/exos.py
index e87189f92e..72bc527d7d 100644
--- a/lib/ansible/plugins/cliconf/exos.py
+++ b/lib/ansible/plugins/cliconf/exos.py
@@ -19,6 +19,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: exos
+short_description: Use exos cliconf to run command on Extreme EXOS platform
+description:
+  - This exos plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Extreme EXOS network devices.
+version_added: "2.6"
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/frr.py b/lib/ansible/plugins/cliconf/frr.py
index e3201de7dd..be80b04aec 100644
--- a/lib/ansible/plugins/cliconf/frr.py
+++ b/lib/ansible/plugins/cliconf/frr.py
@@ -25,8 +25,8 @@ author: Ansible Networking Team
 cliconf: frr
 short_description: Use frr cliconf to run command on Free Range Routing platform
 description:
-  - This frr plugin provides low level abstraction api's for
-    sending and receiving CLI commands from devices running frr.
+  - This frr plugin provides low level abstraction apis for
+    sending and receiving CLI commands from FRR network devices.
 version_added: "2.8"
 """
 
diff --git a/lib/ansible/plugins/cliconf/ios.py b/lib/ansible/plugins/cliconf/ios.py
index a90b829c67..de1b6face2 100644
--- a/lib/ansible/plugins/cliconf/ios.py
+++ b/lib/ansible/plugins/cliconf/ios.py
@@ -19,6 +19,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+author: Ansible Networking Team
+cliconf: ios
+short_description: Use ios cliconf to run command on Cisco IOS platform
+description:
+  - This ios plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Cisco IOS network devices.
+version_added: "2.4"
+"""
+
 import re
 import time
 import json
diff --git a/lib/ansible/plugins/cliconf/iosxr.py b/lib/ansible/plugins/cliconf/iosxr.py
index d78e52f078..1e791c4b0c 100644
--- a/lib/ansible/plugins/cliconf/iosxr.py
+++ b/lib/ansible/plugins/cliconf/iosxr.py
@@ -19,6 +19,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+author: Ansible Networking Team
+cliconf: iosxr
+short_description: Use iosxr cliconf to run command on Cisco IOS XR platform
+description:
+  - This iosxr plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Cisco IOS XR network devices.
+version_added: "2.4"
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/ironware.py b/lib/ansible/plugins/cliconf/ironware.py
index ebf24601f8..ecf35e8e48 100644
--- a/lib/ansible/plugins/cliconf/ironware.py
+++ b/lib/ansible/plugins/cliconf/ironware.py
@@ -19,6 +19,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: ironware
+short_description: Use ironware cliconf to run command on Extreme Ironware platform
+description:
+  - This ironware plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Extreme Ironware network devices.
+version_added: "2.5"
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/junos.py b/lib/ansible/plugins/cliconf/junos.py
index 548b1b37c3..a928fe8d1f 100644
--- a/lib/ansible/plugins/cliconf/junos.py
+++ b/lib/ansible/plugins/cliconf/junos.py
@@ -19,6 +19,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+author: Ansible Networking Team
+cliconf: junos
+short_description: Use junos cliconf to run command on Juniper Junos OS platform
+description:
+  - This junos plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Juniper Junos OS network devices.
+version_added: "2.4"
+"""
+
 import json
 import re
 
diff --git a/lib/ansible/plugins/cliconf/nos.py b/lib/ansible/plugins/cliconf/nos.py
index f5e07ae7cd..558f60ae8b 100644
--- a/lib/ansible/plugins/cliconf/nos.py
+++ b/lib/ansible/plugins/cliconf/nos.py
@@ -19,6 +19,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: nos
+short_description: Use nos cliconf to run command on Extreme NOS platform
+description:
+  - This nos plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Extreme NOS network devices.
+version_added: "2.7"
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/nxos.py b/lib/ansible/plugins/cliconf/nxos.py
index b3b2480000..dac95a22af 100644
--- a/lib/ansible/plugins/cliconf/nxos.py
+++ b/lib/ansible/plugins/cliconf/nxos.py
@@ -19,6 +19,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+author: Ansible Networking Team
+cliconf: nxos
+short_description: Use nxos cliconf to run command on Cisco NX-OS platform
+description:
+  - This nxos plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Cicso NX-OS network devices.
+version_added: "2.4"
+"""
+
 import json
 import re
 
diff --git a/lib/ansible/plugins/cliconf/onyx.py b/lib/ansible/plugins/cliconf/onyx.py
index 4d66bdaad7..8195634b65 100644
--- a/lib/ansible/plugins/cliconf/onyx.py
+++ b/lib/ansible/plugins/cliconf/onyx.py
@@ -19,6 +19,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: onyx
+short_description: Use onyx cliconf to run command on Mellanox ONYX platform
+description:
+  - This onyx plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Mellanox ONYX network devices.
+version_added: "2.5"
+"""
+
 import json
 
 from itertools import chain
diff --git a/lib/ansible/plugins/cliconf/routeros.py b/lib/ansible/plugins/cliconf/routeros.py
index 2c5a922766..38b73fe5b0 100644
--- a/lib/ansible/plugins/cliconf/routeros.py
+++ b/lib/ansible/plugins/cliconf/routeros.py
@@ -19,6 +19,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: routeros
+short_description: Use routeros cliconf to run command on MikroTik RouterOS platform
+description:
+  - This routeros plugin provides low level abstraction apis for
+    sending and receiving CLI commands from MikroTik RouterOS network devices.
+version_added: "2.7"
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/slxos.py b/lib/ansible/plugins/cliconf/slxos.py
index 4cdbaedc7e..5c71e2d23a 100644
--- a/lib/ansible/plugins/cliconf/slxos.py
+++ b/lib/ansible/plugins/cliconf/slxos.py
@@ -19,6 +19,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: slxos
+short_description: Use slxos cliconf to run command on Extreme SLX-OS platform
+description:
+  - This slxos plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Extreme SLX-OS network devices.
+version_added: "2.6"
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/voss.py b/lib/ansible/plugins/cliconf/voss.py
index f105266819..7cf832d5ff 100644
--- a/lib/ansible/plugins/cliconf/voss.py
+++ b/lib/ansible/plugins/cliconf/voss.py
@@ -19,6 +19,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+cliconf: voss
+short_description: Use voss cliconf to run command on Extreme VOSS platform
+description:
+  - This voss plugin provides low level abstraction apis for
+    sending and receiving CLI commands from Extreme VOSS network devices.
+version_added: "2.7"
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/cliconf/vyos.py b/lib/ansible/plugins/cliconf/vyos.py
index a5b9f42f9c..340849e0c6 100644
--- a/lib/ansible/plugins/cliconf/vyos.py
+++ b/lib/ansible/plugins/cliconf/vyos.py
@@ -19,6 +19,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+DOCUMENTATION = """
+---
+author: Ansible Networking Team
+cliconf: vyos
+short_description: Use vyos cliconf to run command on VyOS platform
+description:
+  - This vyos plugin provides low level abstraction apis for
+    sending and receiving CLI commands from VyOS network devices.
+version_added: "2.4"
+"""
+
 import re
 import json
 
diff --git a/lib/ansible/plugins/loader.py b/lib/ansible/plugins/loader.py
index 7e1236318a..6d1ae7d3e8 100644
--- a/lib/ansible/plugins/loader.py
+++ b/lib/ansible/plugins/loader.py
@@ -772,4 +772,5 @@ httpapi_loader = PluginLoader(
     'ansible.plugins.httpapi',
     C.DEFAULT_HTTPAPI_PLUGIN_PATH,
     'httpapi_plugins',
+    required_base_class='HttpApiBase',
 )