centralize doc/config plugin lists (#38775)

* centralize doc/config plugin lists

also update list for generation in docsite
added note to ensure they are in sync

* updated shell page to list plugins

added some more docs hinting at plugins being configurable

* fix edit link for plugins

docs/docsite/Makefile

@@ -26,7 +26,7 @@ ifdef PLUGINS
 	PLUGIN_ARGS = -l $(PLUGINS)
 endif
 
-DOC_PLUGINS ?= cache callback connection inventory lookup strategy vars
+DOC_PLUGINS ?= cache callback connection inventory lookup shell strategy vars
 
 assertrst:
 ifndef rst

docs/docsite/rst/plugins/shell.rst

@@ -1,7 +1,10 @@
+.. contents:: Topics
+
 Shell Plugins
 -------------
 
-Shell plugins work transparently to ensure that the basic commands Ansible runs are properly formatted to work with the target machine.
+Shell plugins work to ensure that the basic commands Ansible runs are properly formatted to work with
+the target machine and allow the user to configure certain behaviours related to how Ansible executes tasks.
 
 .. _enabling_shell:
 
@@ -11,18 +14,26 @@ Enabling Shell Plugins
 You can add a custom shell plugin by dropping it into a ``shell_plugins`` directory adjacent to your play, inside a role,
 or by putting it in one of the shell plugin directory sources configured in :doc:`ansible.cfg <../config>`.
 
-.. warning:: You should not alter the configuration for these plugins unless you have a setup
+.. warning:: You should not alter which plugin is used unless you have a setup in which the default ``/bin/sh``
-             in which the default ``/bin/sh`` is not a POSIX compatible shell or is not availble for execution.
+ is not a POSIX compatible shell or is not availble for execution.
 
 .. _using_shell:
 
 Using Shell Plugins
 +++++++++++++++++++
 
-In addition to the default configuration settings in :doc:`../config`,
+In addition to the default configuration settings in :doc:`../config`, you can use
-you can use a 'connection variable' :ref:`ansible_shell_type` to select the plugin to use. 
+a 'connection variable' :ref:`ansible_shell_type` to select the plugin to use.
 In this case, you will also want to update the :ref:`ansible_executable` to match.
 
+You can further control the settings for each plugin via other configuration options
+detailed in the plugin themsleves (linked below).
+
+.. toctree:: :maxdepth: 1
+    :glob:
+
+    shell/*
+
 .. seealso::
 
    :doc:`../user_guide/playbooks`

docs/templates/plugin.rst.j2

@@ -402,4 +402,8 @@ Author
 {% endif %}
 
 .. hint::
+{%   if plugin_type == 'module' %}
     If you notice any issues in this documentation you can `edit this document <https://github.com/ansible/ansible/edit/devel/lib/ansible/modules/@{ source }@?description=%3C!---%20Your%20description%20here%20--%3E%0A%0A%2Blabel:%20docsite_pr>`_ to improve it.
+{% else %}
+    If you notice any issues in this documentation you can `edit this document <https://github.com/ansible/ansible/edit/devel/lib/ansible/plugins/@{ plugin_type }@/@{ source }@_` to improve it.
+{% endif %}

lib/ansible/cli/doc.py

@@ -72,8 +72,7 @@ class DocCLI(CLI):
                                help='**For internal testing only** Show documentation for all plugins.')
         self.parser.add_option("-t", "--type", action="store", default='module', dest='type', type='choice',
                                help='Choose which plugin type (defaults to "module")',
-                               choices=['cache', 'callback', 'connection', 'inventory', 'lookup', 'module', 'shell', 'strategy', 'vars'])
+                               choices=C.DOCUMENTABLE_PLUGINS)
-
         super(DocCLI, self).parse()
 
         if [self.options.all_plugins, self.options.list_dir, self.options.list_files, self.options.show_snippet].count(True) > 1:

lib/ansible/constants.py

@@ -91,6 +91,10 @@ DEFAULT_SUDO_PASS = None
 DEFAULT_REMOTE_PASS = None
 DEFAULT_SUBSET = None
 DEFAULT_SU_PASS = None
+# FIXME: expand to other plugins, but never doc fragments
+CONFIGURABLE_PLUGINS = ('cache', 'callback', 'connection', 'inventory', 'lookup', 'shell')
+# NOTE: always update the docs/docsite/Makefile to match
+DOCUMENTABLE_PLUGINS = CONFIGURABLE_PLUGINS + ('module', 'strategy', 'vars')
 IGNORE_FILES = ("COPYING", "CONTRIBUTING", "LICENSE", "README", "VERSION", "GUIDELINES")  # ignore during module search
 INTERNAL_RESULT_KEYS = ('add_host', 'add_group')
 LOCALHOST = ('127.0.0.1', 'localhost', '::1')

lib/ansible/plugins/loader.py

@@ -209,9 +209,8 @@ class PluginLoader:
         if self.class_name:
             type_name = get_plugin_class(self.class_name)
 
-            # FIXME: expand to other plugins, but never doc fragments
             # if type name != 'module_doc_fragment':
-            if type_name in ('callback', 'connection', 'inventory', 'lookup', 'shell'):
+            if type_name in C.CONFIGURABLE_PLUGINS:
                 dstring = get_docstring(path, fragment_loader, verbose=False, ignore_errors=True)[0]
 
                 if dstring and 'options' in dstring and isinstance(dstring['options'], dict):