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

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

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

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

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

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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

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
 

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
+  - This eos plugin provides low level abstraction apis for
-    sending and receiving CLI commands from eos network devices.
+    sending and receiving CLI commands from Arista EOS network devices.
-version_added: "2.7"
+version_added: "2.4"
 options:
   eos_use_sessions:
     type: int

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
 

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
+  - This frr plugin provides low level abstraction apis for
-    sending and receiving CLI commands from devices running frr.
+    sending and receiving CLI commands from FRR network devices.
 version_added: "2.8"
 """
 

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

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
 

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
 

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
 

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
 

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
 

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

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
 

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
 

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
 

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
 

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',
 )