From bdbb89378fd08597d0056e06bec352c4942d43cf Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Mon, 16 Apr 2018 09:29:49 -0400 Subject: [PATCH] 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 | 2 +- docs/docsite/rst/plugins/shell.rst | 21 ++++++++++++++++----- docs/templates/plugin.rst.j2 | 4 ++++ lib/ansible/cli/doc.py | 3 +-- lib/ansible/constants.py | 4 ++++ lib/ansible/plugins/loader.py | 3 +-- 6 files changed, 27 insertions(+), 10 deletions(-) diff --git a/docs/docsite/Makefile b/docs/docsite/Makefile index 1e6495c424b..aafcdb00699 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 strategy vars +DOC_PLUGINS ?= cache callback connection inventory lookup shell strategy vars assertrst: ifndef rst diff --git a/docs/docsite/rst/plugins/shell.rst b/docs/docsite/rst/plugins/shell.rst index d4e70dde795..c0341b6934d 100644 --- a/docs/docsite/rst/plugins/shell.rst +++ b/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 - in which the default ``/bin/sh`` is not a POSIX compatible shell or is not availble for execution. +.. warning:: You should not alter which plugin is used unless you have a setup in which the default ``/bin/sh`` + 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`, -you can use a 'connection variable' :ref:`ansible_shell_type` to select the plugin to use. +In addition to the default configuration settings in :doc:`../config`, you can 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` diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2 index 2ee845185ed..ed52a5e3bfd 100644 --- a/docs/templates/plugin.rst.j2 +++ b/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 `_ to improve it. +{% else %} + If you notice any issues in this documentation you can `edit this document 1: diff --git a/lib/ansible/constants.py b/lib/ansible/constants.py index 16d57dbd12c..cdf2d5fff8e 100644 --- a/lib/ansible/constants.py +++ b/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') diff --git a/lib/ansible/plugins/loader.py b/lib/ansible/plugins/loader.py index d56182f6afa..4332a5a8629 100644 --- a/lib/ansible/plugins/loader.py +++ b/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):