From 2d5908255a26d90b4ddec1235f064662462c0dd1 Mon Sep 17 00:00:00 2001
From: Peter Sprygada <privateip@users.noreply.github.com>
Date: Mon, 7 Aug 2017 07:19:31 -0400
Subject: [PATCH] add parse_cli and parse_cli_textfsm to documentation (#27755)

* add parse_cli and parse_cli_textfsm to documentation

* Minor edits.
---
 docs/docsite/rst/playbooks_filters.rst | 45 ++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/docs/docsite/rst/playbooks_filters.rst b/docs/docsite/rst/playbooks_filters.rst
index 143ec8d69e..98a2f2b68b 100644
--- a/docs/docsite/rst/playbooks_filters.rst
+++ b/docs/docsite/rst/playbooks_filters.rst
@@ -318,6 +318,51 @@ address. For example, to get the IP address itself from a CIDR, you can use::
 More information about ``ipaddr`` filter and complete usage guide can be found
 in :doc:`playbooks_filters_ipaddr`.
 
+.. _network_filters:
+
+Network CLI filters
+```````````````````
+
+.. versionadded:: 2.4
+
+To convert the output of a network device CLI command into structured JSON
+output, use the ``parse_cli`` filter::
+
+  {{ output | parse_cli('path/to/spec') }}
+
+The ``parse_cli`` filter will load the spec file and pass the command output
+through, it returning JSON output.  The spec file is a YAML yaml that defines
+how to parse the CLI output.  
+
+The spec file should be valid formatted YAML.  It defines how to parse the CLI
+output and return JSON data.  Below is an example of a valid spec file that
+will parse the output from the ``show vlan`` command.::
+
+    ---
+    vlan:
+      vlan_id: "{{ item.vlan_id }}"
+      name: "{{ item.name }}"
+      enabled: "{{ item.state != 'act/lshut' }}"
+      state: "{{ item.state }}"
+
+    attributes:
+      vlans:
+        type: list
+        value: "{{ vlan }}"
+        items: "^(?P<vlan_id>\\d+)\\s+(?P<name>\\w+)\\s+(?P<state>active|act/lshut|suspended)"
+      state_static:
+        value: present
+
+The spec file above will return a JSON data structure that is a list of hashs
+with the parsed VLAN information.
+
+The network filters also support parsing the output of a CLI command using the
+TextFSM library.  To parse the CLI output with TextFSM use the following
+filter::
+
+  {{ output | parse_cli_textfsm('path/to/fsm') }}
+
+Use of the TextFSM filter requires the TextFSM library to be installed.
 
 .. _hash_filters: