From ad203a7dbdbcab9af0b89a577433af860b542e01 Mon Sep 17 00:00:00 2001
From: Nathaniel Case <ncase@redhat.com>
Date: Mon, 21 Jun 2021 10:47:42 -0400
Subject: [PATCH] Add page describing terminal plugins to docsite (#75066)

---
 .../fragments/terminal-documentation.yaml     |  3 ++
 docs/docsite/rst/plugins/plugins.rst          |  1 +
 docs/docsite/rst/plugins/terminal.rst         | 47 +++++++++++++++++++
 3 files changed, 51 insertions(+)
 create mode 100644 changelogs/fragments/terminal-documentation.yaml
 create mode 100644 docs/docsite/rst/plugins/terminal.rst

diff --git a/changelogs/fragments/terminal-documentation.yaml b/changelogs/fragments/terminal-documentation.yaml
new file mode 100644
index 00000000000..984772b944c
--- /dev/null
+++ b/changelogs/fragments/terminal-documentation.yaml
@@ -0,0 +1,3 @@
+---
+bugfixes:
+  - Added page describing terminal plugins to docsite
diff --git a/docs/docsite/rst/plugins/plugins.rst b/docs/docsite/rst/plugins/plugins.rst
index ac9a862eb2a..2a2c6322531 100644
--- a/docs/docsite/rst/plugins/plugins.rst
+++ b/docs/docsite/rst/plugins/plugins.rst
@@ -25,6 +25,7 @@ This section covers the various types of plugins that are included with Ansible:
    netconf
    shell
    strategy
+   terminal
    vars
    ../user_guide/playbooks_filters
    ../user_guide/playbooks_tests
diff --git a/docs/docsite/rst/plugins/terminal.rst b/docs/docsite/rst/plugins/terminal.rst
new file mode 100644
index 00000000000..006b75235bd
--- /dev/null
+++ b/docs/docsite/rst/plugins/terminal.rst
@@ -0,0 +1,47 @@
+.. _terminal_plugins:
+
+Terminal Plugins
+================
+
+.. contents::
+   :local:
+   :depth: 2
+
+Terminal plugins contain information on how to prepare a particular network device's SSH shell is properly initialized to be used with Ansible. This typically includes disabling automatic paging, detecting errors in output, and enabling privileged mode if supported and required on the device.
+
+These plugins correspond one-to-one to network device platforms. Ansible loads the appropriate terminal plugin automatically based on the ``ansible_network_os`` variable.
+
+.. _enabling_terminal:
+
+Adding terminal plugins
+-------------------------
+
+You can extend Ansible to support other network devices by dropping a custom plugin into the ``terminal_plugins`` directory.
+
+.. _using_terminal:
+
+Using terminal plugins
+------------------------
+
+The terminal plugin to use is determined automatically from the ``ansible_network_os`` variable. There should be no reason to override this functionality.
+
+Terminal plugins operate without configuration. All options to control the terminal are exposed in the ``network_cli`` connection plugin.
+
+Plugins are self-documenting. Each plugin should document its configuration options.
+
+.. _terminal_plugin_list:
+
+Viewing terminal plugins
+------------------------
+
+These plugins have migrated to collections on `Ansible Galaxy <https://galaxy.ansible.com>`_. If you installed Ansible version 2.10 or later using ``pip``, you have access to several terminal plugins. To list all available terminal plugins on your control node, type ``ansible-doc -t terminal -l``. To view plugin-specific documentation and examples, use ``ansible-doc -t terminal``.
+
+
+.. 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.libera.chat <https://libera.chat/>`_
+       #ansible-network IRC chat channel