Adding upstream version 2.14.3.upstream/2.14.3upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

2 files changed, 127 insertions, 0 deletions

diff --git a/docs/bin/find-plugin-refs.py b/docs/bin/find-plugin-refs.py
new file mode 100755
index 0000000..d603409
--- /dev/null
+++ b/docs/bin/find-plugin-refs.py
@@ -0,0 +1,85 @@
+#!/usr/bin/env python
+
+# To run this script, first make webdocs in the toplevel of the checkout.  This will generate all
+# rst files from their sources.  Then run this script ./docs/bin/find-plugin-refs.py
+#
+# No output means that there are no longer any bare module and plugin names referenced via :ref:
+#
+# For my listing of what needs to be changed after running this script, see the comment at the end
+# of the file
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import glob
+import os
+import re
+
+from ansible.module_utils._text import to_text
+
+
+TOPDIR = os.path.join(os.path.dirname(__file__), '..', 'docsite', 'rst')
+
+
+def plugin_names(topdir):
+    plugins = set()
+
+    # Modules are in a separate directory
+    for module_filename in glob.glob(os.path.join(topdir, 'modules', '*_module.rst')):
+        module_filename = os.path.basename(module_filename)
+        module_name = module_filename[:module_filename.index('_module.rst')]
+        plugins.add(module_name)
+
+    for plugin_filename in glob.glob(os.path.join(topdir, 'plugins', '*', '*.rst')):
+        plugin_filename = os.path.basename(plugin_filename)
+        plugin_name = plugin_filename[:plugin_filename.index('.rst')]
+        plugins.add(plugin_name)
+
+    return plugins
+
+
+def process_refs(topdir, plugin_names):
+    REF_RE = re.compile(':ref:`([^`]*)`')
+    LABEL_RE = re.compile('<([^>]*)>$')
+
+    # Walk the whole docs tree looking for :ref:.  Anywhere those are found, search for `([^`]*)`
+    for dirpath, dirnames, filenames in os.walk(topdir):
+        for filename in filenames:
+            with open(os.path.join(dirpath, filename), 'rb') as f:
+                data = f.read()
+                data = to_text(data)
+                for ref_match in re.finditer(REF_RE, data):
+                    label = ref_match.group(1)
+
+                    # If the ref label includes "<", then search for the label inside of the "<>"
+                    label_match = re.search(LABEL_RE, label)
+                    if label_match:
+                        label = label_match.group(1)
+
+                    # If the ref label is listed in plugins, then print that the file contains an unported ref
+                    if label in plugin_names:
+                        print(':ref:`{0}` matching plugin {1} was found in {2}'.format(ref_match.group(1), label, os.path.join(dirpath, filename)))
+
+
+if __name__ == '__main__':
+
+    plugins = plugin_names(TOPDIR)
+
+    process_refs(TOPDIR, plugins)
+
+    # Fixes needed: docs/bin/plugin_formatter.py
+    # - t = _MODULE.sub(r":ref:`\1 <\1>`", t)
+    # + t = _MODULE.sub(r":ref:`\1 <module_\1>`", t)
+    #
+    # These have @{module}@ in the template and need to have something like module_@{module}@
+    # If any of these list plugins as well as modules, they will need to have a conditional or extra
+    # data passed in to handle that in a generic fashion:
+    #
+    # docs/templates/list_of_CATEGORY_modules.rst.j2
+    # docs/templates/list_of_CATEGORY_plugins.rst.j2
+    # docs/templates/modules_by_support.rst.j2
+    #
+    # These are just a simple manual fix:
+    # :ref:`command` matching plugin command was found in ./../docsite/rst/user_guide/intro_adhoc.rst
+    # :ref:`shell` matching plugin shell was found in ./../docsite/rst/user_guide/intro_adhoc.rst
+    # :ref:`config` matching plugin config was found in ./../docsite/rst/installation_guide/intro_configuration.rst
diff --git a/docs/bin/testing_formatter.sh b/docs/bin/testing_formatter.sh
new file mode 100755
index 0000000..f3a41e1
--- /dev/null
+++ b/docs/bin/testing_formatter.sh
@@ -0,0 +1,42 @@
+#!/bin/sh
+
+set -eux
+
+FILENAME=../docsite/rst/dev_guide/testing/sanity/index.rst
+
+cat <<- EOF >$FILENAME.new
+.. _all_sanity_tests:
+
+Sanity Tests
+============
+
+The following sanity tests are available as \`\`--test\`\` options for \`\`ansible-test sanity\`\`.
+This list is also available using \`\`ansible-test sanity --list-tests --allow-disabled\`\`.
+
+For information on how to run these tests, see :ref:\`sanity testing guide <testing_sanity>\`.
+
+.. toctree::
+   :maxdepth: 1
+
+$(for test in $(../../bin/ansible-test sanity --list-tests --allow-disabled); do echo "   ${test}"; done)
+
+EOF
+
+# By default use sha1sum which exists on Linux, if not present select the correct binary
+# based on platform defaults
+SHA_CMD="sha1sum"
+if ! command -v ${SHA_CMD} > /dev/null 2>&1; then
+    if command -v sha1 > /dev/null 2>&1; then
+        SHA_CMD="sha1"
+    elif command -v shasum > /dev/null 2>&1; then
+        SHA_CMD="shasum"
+    else
+        # exit early with an error if no hashing binary can be found since it is required later
+        exit 1
+    fi
+fi
+
+# Put file into place if it has changed
+if [ ! -f "${FILENAME}" ] || [ "$(${SHA_CMD} <$FILENAME)" != "$(${SHA_CMD} <$FILENAME.new)" ]; then
+    mv -f $FILENAME.new $FILENAME
+fi