From c89f98168d0ba87c54bbc978928cb2d4f54afef2 Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Wed, 3 Jun 2015 14:53:19 -0500 Subject: [PATCH] Add the hacking directory to v1 --- v1/hacking/README.md | 48 ++++ v1/hacking/authors.sh | 14 ++ v1/hacking/env-setup | 78 ++++++ v1/hacking/env-setup.fish | 67 +++++ v1/hacking/get_library.py | 29 +++ v1/hacking/module_formatter.py | 447 +++++++++++++++++++++++++++++++++ v1/hacking/templates/rst.j2 | 211 ++++++++++++++++ v1/hacking/test-module | 193 ++++++++++++++ v1/hacking/update.sh | 3 + 9 files changed, 1090 insertions(+) create mode 100644 v1/hacking/README.md create mode 100755 v1/hacking/authors.sh create mode 100644 v1/hacking/env-setup create mode 100644 v1/hacking/env-setup.fish create mode 100755 v1/hacking/get_library.py create mode 100755 v1/hacking/module_formatter.py create mode 100644 v1/hacking/templates/rst.j2 create mode 100755 v1/hacking/test-module create mode 100755 v1/hacking/update.sh diff --git a/v1/hacking/README.md b/v1/hacking/README.md new file mode 100644 index 00000000000..ae8db7e3a9b --- /dev/null +++ b/v1/hacking/README.md @@ -0,0 +1,48 @@ +'Hacking' directory tools +========================= + +Env-setup +--------- + +The 'env-setup' script modifies your environment to allow you to run +ansible from a git checkout using python 2.6+. (You may not use +python 3 at this time). + +First, set up your environment to run from the checkout: + + $ source ./hacking/env-setup + +You will need some basic prerequisites installed. If you do not already have them +and do not wish to install them from your operating system package manager, you +can install them from pip + + $ easy_install pip # if pip is not already available + $ pip install pyyaml jinja2 nose passlib pycrypto + +From there, follow ansible instructions on docs.ansible.com as normal. + +Test-module +----------- + +'test-module' is a simple program that allows module developers (or testers) to run +a module outside of the ansible program, locally, on the current machine. + +Example: + + $ ./hacking/test-module -m lib/ansible/modules/core/commands/shell -a "echo hi" + +This is a good way to insert a breakpoint into a module, for instance. + +Module-formatter +---------------- + +The module formatter is a script used to generate manpages and online +module documentation. This is used by the system makefiles and rarely +needs to be run directly. + +Authors +------- +'authors' is a simple script that generates a list of everyone who has +contributed code to the ansible repository. + + diff --git a/v1/hacking/authors.sh b/v1/hacking/authors.sh new file mode 100755 index 00000000000..7c97840b2fb --- /dev/null +++ b/v1/hacking/authors.sh @@ -0,0 +1,14 @@ +#!/bin/sh +# script from http://stackoverflow.com/questions/12133583 +set -e + +# Get a list of authors ordered by number of commits +# and remove the commit count column +AUTHORS=$(git --no-pager shortlog -nse | cut -f 2- | sort -f) +if [ -z "$AUTHORS" ] ; then + echo "Authors list was empty" + exit 1 +fi + +# Display the authors list and write it to the file +echo "$AUTHORS" | tee "$(git rev-parse --show-toplevel)/AUTHORS.TXT" diff --git a/v1/hacking/env-setup b/v1/hacking/env-setup new file mode 100644 index 00000000000..29f4828410a --- /dev/null +++ b/v1/hacking/env-setup @@ -0,0 +1,78 @@ +# usage: source hacking/env-setup [-q] +# modifies environment for running Ansible from checkout + +# Default values for shell variables we use +PYTHONPATH=${PYTHONPATH-""} +PATH=${PATH-""} +MANPATH=${MANPATH-""} +verbosity=${1-info} # Defaults to `info' if unspecified + +if [ "$verbosity" = -q ]; then + verbosity=silent +fi + +# When run using source as directed, $0 gets set to bash, so we must use $BASH_SOURCE +if [ -n "$BASH_SOURCE" ] ; then + HACKING_DIR=$(dirname "$BASH_SOURCE") +elif [ $(basename -- "$0") = "env-setup" ]; then + HACKING_DIR=$(dirname "$0") +# Works with ksh93 but not pdksh +elif [ -n "$KSH_VERSION" ] && echo $KSH_VERSION | grep -qv '^@(#)PD KSH'; then + HACKING_DIR=$(dirname "${.sh.file}") +else + HACKING_DIR="$PWD/hacking" +fi +# The below is an alternative to readlink -fn which doesn't exist on OS X +# Source: http://stackoverflow.com/a/1678636 +FULL_PATH=$(python -c "import os; print(os.path.realpath('$HACKING_DIR'))") +ANSIBLE_HOME=$(dirname "$FULL_PATH") + +PREFIX_PYTHONPATH="$ANSIBLE_HOME" +PREFIX_PATH="$ANSIBLE_HOME/bin" +PREFIX_MANPATH="$ANSIBLE_HOME/docs/man" + +expr "$PYTHONPATH" : "${PREFIX_PYTHONPATH}.*" > /dev/null || export PYTHONPATH="$PREFIX_PYTHONPATH:$PYTHONPATH" +expr "$PATH" : "${PREFIX_PATH}.*" > /dev/null || export PATH="$PREFIX_PATH:$PATH" +expr "$MANPATH" : "${PREFIX_MANPATH}.*" > /dev/null || export MANPATH="$PREFIX_MANPATH:$MANPATH" + +# +# Generate egg_info so that pkg_resources works +# + +# Do the work in a function so we don't repeat ourselves later +gen_egg_info() +{ + if [ -e "$PREFIX_PYTHONPATH/ansible.egg-info" ] ; then + rm -r "$PREFIX_PYTHONPATH/ansible.egg-info" + fi + python setup.py egg_info +} + +if [ "$ANSIBLE_HOME" != "$PWD" ] ; then + current_dir="$PWD" +else + current_dir="$ANSIBLE_HOME" +fi +cd "$ANSIBLE_HOME" +if [ "$verbosity" = silent ] ; then + gen_egg_info > /dev/null 2>&1 +else + gen_egg_info +fi +cd "$current_dir" + +if [ "$verbosity" != silent ] ; then + cat <<- EOF + + Setting up Ansible to run out of checkout... + + PATH=$PATH + PYTHONPATH=$PYTHONPATH + MANPATH=$MANPATH + + Remember, you may wish to specify your host file with -i + + Done! + + EOF +fi diff --git a/v1/hacking/env-setup.fish b/v1/hacking/env-setup.fish new file mode 100644 index 00000000000..9deffb4e3d9 --- /dev/null +++ b/v1/hacking/env-setup.fish @@ -0,0 +1,67 @@ +#!/usr/bin/env fish +# usage: . ./hacking/env-setup [-q] +# modifies environment for running Ansible from checkout +set HACKING_DIR (dirname (status -f)) +set FULL_PATH (python -c "import os; print(os.path.realpath('$HACKING_DIR'))") +set ANSIBLE_HOME (dirname $FULL_PATH) +set PREFIX_PYTHONPATH $ANSIBLE_HOME/ +set PREFIX_PATH $ANSIBLE_HOME/bin +set PREFIX_MANPATH $ANSIBLE_HOME/docs/man + +# Set PYTHONPATH +if not set -q PYTHONPATH + set -gx PYTHONPATH $PREFIX_PYTHONPATH +else + switch PYTHONPATH + case "$PREFIX_PYTHONPATH*" + case "*" + echo "Appending PYTHONPATH" + set -gx PYTHONPATH "$PREFIX_PYTHONPATH:$PYTHONPATH" + end +end + +# Set PATH +if not contains $PREFIX_PATH $PATH + set -gx PATH $PREFIX_PATH $PATH +end + +# Set MANPATH +if not contains $PREFIX_MANPATH $MANPATH + if not set -q MANPATH + set -gx MANPATH $PREFIX_MANPATH + else + set -gx MANPATH $PREFIX_MANPATH $MANPATH + end +end + +set -gx ANSIBLE_LIBRARY $ANSIBLE_HOME/library + +# Generate egg_info so that pkg_resources works +pushd $ANSIBLE_HOME +python setup.py egg_info +if test -e $PREFIX_PYTHONPATH/ansible*.egg-info + rm -r $PREFIX_PYTHONPATH/ansible*.egg-info +end +mv ansible*egg-info $PREFIX_PYTHONPATH +popd + + +if set -q argv + switch $argv + case '-q' '--quiet' + case '*' + echo "" + echo "Setting up Ansible to run out of checkout..." + echo "" + echo "PATH=$PATH" + echo "PYTHONPATH=$PYTHONPATH" + echo "ANSIBLE_LIBRARY=$ANSIBLE_LIBRARY" + echo "MANPATH=$MANPATH" + echo "" + + echo "Remember, you may wish to specify your host file with -i" + echo "" + echo "Done!" + echo "" + end +end diff --git a/v1/hacking/get_library.py b/v1/hacking/get_library.py new file mode 100755 index 00000000000..571183b688c --- /dev/null +++ b/v1/hacking/get_library.py @@ -0,0 +1,29 @@ +#!/usr/bin/env python + +# (c) 2014, Will Thames +# +# This file is part of Ansible +# +# Ansible is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# Ansible is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Ansible. If not, see . +# + +import ansible.constants as C +import sys + +def main(): + print C.DEFAULT_MODULE_PATH + return 0 + +if __name__ == '__main__': + sys.exit(main()) diff --git a/v1/hacking/module_formatter.py b/v1/hacking/module_formatter.py new file mode 100755 index 00000000000..acddd700930 --- /dev/null +++ b/v1/hacking/module_formatter.py @@ -0,0 +1,447 @@ +#!/usr/bin/env python +# (c) 2012, Jan-Piet Mens +# (c) 2012-2014, Michael DeHaan and others +# +# This file is part of Ansible +# +# Ansible is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# Ansible is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Ansible. If not, see . +# + +import os +import glob +import sys +import yaml +import codecs +import json +import ast +import re +import optparse +import time +import datetime +import subprocess +import cgi +from jinja2 import Environment, FileSystemLoader + +from ansible.utils import module_docs +from ansible.utils.vars import merge_hash + +##################################################################################### +# constants and paths + +# if a module is added in a version of Ansible older than this, don't print the version added information +# in the module documentation because everyone is assumed to be running something newer than this already. +TO_OLD_TO_BE_NOTABLE = 1.0 + +# Get parent directory of the directory this script lives in +MODULEDIR=os.path.abspath(os.path.join( + os.path.dirname(os.path.realpath(__file__)), os.pardir, 'lib', 'ansible', 'modules' +)) + +# The name of the DOCUMENTATION template +EXAMPLE_YAML=os.path.abspath(os.path.join( + os.path.dirname(os.path.realpath(__file__)), os.pardir, 'examples', 'DOCUMENTATION.yml' +)) + +_ITALIC = re.compile(r"I\(([^)]+)\)") +_BOLD = re.compile(r"B\(([^)]+)\)") +_MODULE = re.compile(r"M\(([^)]+)\)") +_URL = re.compile(r"U\(([^)]+)\)") +_CONST = re.compile(r"C\(([^)]+)\)") + +DEPRECATED = " (D)" +NOTCORE = " (E)" +##################################################################################### + +def rst_ify(text): + ''' convert symbols like I(this is in italics) to valid restructured text ''' + + t = _ITALIC.sub(r'*' + r"\1" + r"*", text) + t = _BOLD.sub(r'**' + r"\1" + r"**", t) + t = _MODULE.sub(r':ref:`' + r"\1 <\1>" + r"`", t) + t = _URL.sub(r"\1", t) + t = _CONST.sub(r'``' + r"\1" + r"``", t) + + return t + +##################################################################################### + +def html_ify(text): + ''' convert symbols like I(this is in italics) to valid HTML ''' + + t = cgi.escape(text) + t = _ITALIC.sub("" + r"\1" + "", t) + t = _BOLD.sub("" + r"\1" + "", t) + t = _MODULE.sub("" + r"\1" + "", t) + t = _URL.sub("" + r"\1" + "", t) + t = _CONST.sub("" + r"\1" + "", t) + + return t + + +##################################################################################### + +def rst_fmt(text, fmt): + ''' helper for Jinja2 to do format strings ''' + + return fmt % (text) + +##################################################################################### + +def rst_xline(width, char="="): + ''' return a restructured text line of a given length ''' + + return char * width + +##################################################################################### + +def write_data(text, options, outputname, module): + ''' dumps module output to a file or the screen, as requested ''' + + if options.output_dir is not None: + fname = os.path.join(options.output_dir, outputname % module) + fname = fname.replace(".py","") + f = open(fname, 'w') + f.write(text.encode('utf-8')) + f.close() + else: + print text + +##################################################################################### + + +def list_modules(module_dir, depth=0): + ''' returns a hash of categories, each category being a hash of module names to file paths ''' + + categories = dict(all=dict(),_aliases=dict()) + if depth <= 3: # limit # of subdirs + + files = glob.glob("%s/*" % module_dir) + for d in files: + + category = os.path.splitext(os.path.basename(d))[0] + if os.path.isdir(d): + + res = list_modules(d, depth + 1) + for key in res.keys(): + if key in categories: + categories[key] = merge_hash(categories[key], res[key]) + res.pop(key, None) + + if depth < 2: + categories.update(res) + else: + category = module_dir.split("/")[-1] + if not category in categories: + categories[category] = res + else: + categories[category].update(res) + else: + module = category + category = os.path.basename(module_dir) + if not d.endswith(".py") or d.endswith('__init__.py'): + # windows powershell modules have documentation stubs in python docstring + # format (they are not executed) so skip the ps1 format files + continue + elif module.startswith("_") and os.path.islink(d): + source = os.path.splitext(os.path.basename(os.path.realpath(d)))[0] + module = module.replace("_","",1) + if not d in categories['_aliases']: + categories['_aliases'][source] = [module] + else: + categories['_aliases'][source].update(module) + continue + + if not category in categories: + categories[category] = {} + categories[category][module] = d + categories['all'][module] = d + + return categories + +##################################################################################### + +def generate_parser(): + ''' generate an optparse parser ''' + + p = optparse.OptionParser( + version='%prog 1.0', + usage='usage: %prog [options] arg1 arg2', + description='Generate module documentation from metadata', + ) + + p.add_option("-A", "--ansible-version", action="store", dest="ansible_version", default="unknown", help="Ansible version number") + p.add_option("-M", "--module-dir", action="store", dest="module_dir", default=MODULEDIR, help="Ansible library path") + p.add_option("-T", "--template-dir", action="store", dest="template_dir", default="hacking/templates", help="directory containing Jinja2 templates") + p.add_option("-t", "--type", action='store', dest='type', choices=['rst'], default='rst', help="Document type") + p.add_option("-v", "--verbose", action='store_true', default=False, help="Verbose") + p.add_option("-o", "--output-dir", action="store", dest="output_dir", default=None, help="Output directory for module files") + p.add_option("-I", "--includes-file", action="store", dest="includes_file", default=None, help="Create a file containing list of processed modules") + p.add_option('-V', action='version', help='Show version number and exit') + return p + +##################################################################################### + +def jinja2_environment(template_dir, typ): + + env = Environment(loader=FileSystemLoader(template_dir), + variable_start_string="@{", + variable_end_string="}@", + trim_blocks=True, + ) + env.globals['xline'] = rst_xline + + if typ == 'rst': + env.filters['convert_symbols_to_format'] = rst_ify + env.filters['html_ify'] = html_ify + env.filters['fmt'] = rst_fmt + env.filters['xline'] = rst_xline + template = env.get_template('rst.j2') + outputname = "%s_module.rst" + else: + raise Exception("unknown module format type: %s" % typ) + + return env, template, outputname + +##################################################################################### + +def process_module(module, options, env, template, outputname, module_map, aliases): + + fname = module_map[module] + if isinstance(fname, dict): + return "SKIPPED" + + basename = os.path.basename(fname) + deprecated = False + + # ignore files with extensions + if not basename.endswith(".py"): + return + elif module.startswith("_"): + if os.path.islink(fname): + return # ignore, its an alias + deprecated = True + module = module.replace("_","",1) + + print "rendering: %s" % module + + # use ansible core library to parse out doc metadata YAML and plaintext examples + doc, examples, returndocs = module_docs.get_docstring(fname, verbose=options.verbose) + + # crash if module is missing documentation and not explicitly hidden from docs index + if doc is None: + if module in module_docs.BLACKLIST_MODULES: + return "SKIPPED" + else: + sys.stderr.write("*** ERROR: MODULE MISSING DOCUMENTATION: %s, %s ***\n" % (fname, module)) + sys.exit(1) + + if deprecated and 'deprecated' not in doc: + sys.stderr.write("*** ERROR: DEPRECATED MODULE MISSING 'deprecated' DOCUMENTATION: %s, %s ***\n" % (fname, module)) + sys.exit(1) + + if "/core/" in fname: + doc['core'] = True + else: + doc['core'] = False + + if module in aliases: + doc['aliases'] = aliases[module] + + all_keys = [] + + if not 'version_added' in doc: + sys.stderr.write("*** ERROR: missing version_added in: %s ***\n" % module) + sys.exit(1) + + added = 0 + if doc['version_added'] == 'historical': + del doc['version_added'] + else: + added = doc['version_added'] + + # don't show version added information if it's too old to be called out + if added: + added_tokens = str(added).split(".") + added = added_tokens[0] + "." + added_tokens[1] + added_float = float(added) + if added and added_float < TO_OLD_TO_BE_NOTABLE: + del doc['version_added'] + + if 'options' in doc: + for (k,v) in doc['options'].iteritems(): + all_keys.append(k) + + all_keys = sorted(all_keys) + + doc['option_keys'] = all_keys + doc['filename'] = fname + doc['docuri'] = doc['module'].replace('_', '-') + doc['now_date'] = datetime.date.today().strftime('%Y-%m-%d') + doc['ansible_version'] = options.ansible_version + doc['plainexamples'] = examples #plain text + if returndocs: + doc['returndocs'] = yaml.safe_load(returndocs) + else: + doc['returndocs'] = None + + # here is where we build the table of contents... + + text = template.render(doc) + write_data(text, options, outputname, module) + return doc['short_description'] + +##################################################################################### + +def print_modules(module, category_file, deprecated, core, options, env, template, outputname, module_map, aliases): + modstring = module + modname = module + if module in deprecated: + modstring = modstring + DEPRECATED + modname = "_" + module + elif module not in core: + modstring = modstring + NOTCORE + + result = process_module(modname, options, env, template, outputname, module_map, aliases) + + if result != "SKIPPED": + category_file.write(" %s - %s <%s_module>\n" % (modstring, result, module)) + +def process_category(category, categories, options, env, template, outputname): + + module_map = categories[category] + + aliases = {} + if '_aliases' in categories: + aliases = categories['_aliases'] + + category_file_path = os.path.join(options.output_dir, "list_of_%s_modules.rst" % category) + category_file = open(category_file_path, "w") + print "*** recording category %s in %s ***" % (category, category_file_path) + + # TODO: start a new category file + + category = category.replace("_"," ") + category = category.title() + + modules = [] + deprecated = [] + core = [] + for module in module_map.keys(): + + if isinstance(module_map[module], dict): + for mod in module_map[module].keys(): + if mod.startswith("_"): + mod = mod.replace("_","",1) + deprecated.append(mod) + elif '/core/' in module_map[module][mod]: + core.append(mod) + else: + if module.startswith("_"): + module = module.replace("_","",1) + deprecated.append(module) + elif '/core/' in module_map[module]: + core.append(module) + + modules.append(module) + + modules.sort() + + category_header = "%s Modules" % (category.title()) + underscores = "`" * len(category_header) + + category_file.write("""\ +%s +%s + +.. toctree:: :maxdepth: 1 + +""" % (category_header, underscores)) + sections = [] + for module in modules: + if module in module_map and isinstance(module_map[module], dict): + sections.append(module) + continue + else: + print_modules(module, category_file, deprecated, core, options, env, template, outputname, module_map, aliases) + + sections.sort() + for section in sections: + category_file.write("\n%s\n%s\n\n" % (section.replace("_"," ").title(),'-' * len(section))) + category_file.write(".. toctree:: :maxdepth: 1\n\n") + + section_modules = module_map[section].keys() + section_modules.sort() + #for module in module_map[section]: + for module in section_modules: + print_modules(module, category_file, deprecated, core, options, env, template, outputname, module_map[section], aliases) + + category_file.write("""\n\n +.. note:: + - %s: This marks a module as deprecated, which means a module is kept for backwards compatibility but usage is discouraged. The module documentation details page may explain more about this rationale. + - %s: This marks a module as 'extras', which means it ships with ansible but may be a newer module and possibly (but not necessarily) less actively maintained than 'core' modules. + - Tickets filed on modules are filed to different repos than those on the main open source project. Core module tickets should be filed at `ansible/ansible-modules-core on GitHub `_, extras tickets to `ansible/ansible-modules-extras on GitHub `_ +""" % (DEPRECATED, NOTCORE)) + category_file.close() + + # TODO: end a new category file + +##################################################################################### + +def validate_options(options): + ''' validate option parser options ''' + + if not options.module_dir: + print >>sys.stderr, "--module-dir is required" + sys.exit(1) + if not os.path.exists(options.module_dir): + print >>sys.stderr, "--module-dir does not exist: %s" % options.module_dir + sys.exit(1) + if not options.template_dir: + print "--template-dir must be specified" + sys.exit(1) + +##################################################################################### + +def main(): + + p = generate_parser() + + (options, args) = p.parse_args() + validate_options(options) + + env, template, outputname = jinja2_environment(options.template_dir, options.type) + + categories = list_modules(options.module_dir) + last_category = None + category_names = categories.keys() + category_names.sort() + + category_list_path = os.path.join(options.output_dir, "modules_by_category.rst") + category_list_file = open(category_list_path, "w") + category_list_file.write("Module Index\n") + category_list_file.write("============\n") + category_list_file.write("\n\n") + category_list_file.write(".. toctree::\n") + category_list_file.write(" :maxdepth: 1\n\n") + + for category in category_names: + if category.startswith("_"): + continue + category_list_file.write(" list_of_%s_modules\n" % category) + process_category(category, categories, options, env, template, outputname) + + category_list_file.close() + +if __name__ == '__main__': + main() diff --git a/v1/hacking/templates/rst.j2 b/v1/hacking/templates/rst.j2 new file mode 100644 index 00000000000..f6f38e59101 --- /dev/null +++ b/v1/hacking/templates/rst.j2 @@ -0,0 +1,211 @@ +.. _@{ module }@: + +{% if short_description %} +{% set title = module + ' - ' + short_description|convert_symbols_to_format %} +{% else %} +{% set title = module %} +{% endif %} +{% set title_len = title|length %} + +@{ title }@ +@{ '+' * title_len }@ + +.. contents:: + :local: + :depth: 1 + +{# ------------------------------------------ + # + # Please note: this looks like a core dump + # but it isn't one. + # + --------------------------------------------#} + +{% if aliases is defined -%} +Aliases: @{ ','.join(aliases) }@ +{% endif %} + +{% if deprecated is defined -%} +DEPRECATED +---------- + +@{ deprecated }@ +{% endif %} + +Synopsis +-------- + +{% if version_added is defined -%} +.. versionadded:: @{ version_added }@ +{% endif %} + +{% for desc in description -%} +@{ desc | convert_symbols_to_format }@ +{% endfor %} + +{% if options -%} +Options +------- + +.. raw:: html + + + + + + + + + + {% for k in option_keys %} + {% set v = options[k] %} + + + + + {% if v.get('type', 'not_bool') == 'bool' %} + + {% else %} + + {% endif %} + + + {% endfor %} +
parameterrequireddefaultchoicescomments
@{ k }@{% if v.get('required', False) %}yes{% else %}no{% endif %}{% if v['default'] %}@{ v['default'] }@{% endif %}
  • yes
  • no
    {% for choice in v.get('choices',[]) -%}
  • @{ choice }@
    • {% endfor -%}
{% for desc in v.description -%}@{ desc | html_ify }@{% endfor -%}{% if v['version_added'] %} (added in Ansible @{v['version_added']}@){% endif %}
+{% endif %} + +{% if requirements %} +{% for req in requirements %} + +.. note:: Requires @{ req | convert_symbols_to_format }@ + +{% endfor %} +{% endif %} + +{% if examples or plainexamples %} +Examples +-------- + +.. raw:: html + +{% for example in examples %} + {% if example['description'] %}

@{ example['description'] | html_ify }@

{% endif %} +

+ 

+@{ example['code'] | escape | indent(4, True) }@
+
+

+{% endfor %} +
+ +{% if plainexamples %} + +:: + +@{ plainexamples | indent(4, True) }@ +{% endif %} +{% endif %} + + +{% if returndocs %} +Return Values +------------- + +Common return values are documented here :doc:`common_return_values`, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + {% for entry in returndocs %} + + + + + + + + {% if returndocs[entry].type == 'dictionary' %} + + + + {% endif %} + {% endfor %} + +
namedescriptionreturnedtypesample
@{ entry }@ @{ returndocs[entry].description }@ @{ returndocs[entry].returned }@ @{ returndocs[entry].type }@ @{ returndocs[entry].sample}@
contains: + + + + + + + + + + {% for sub in returndocs[entry].contains %} + + + + + + + + {% endfor %} + +
namedescriptionreturnedtypesample
@{ sub }@ @{ returndocs[entry].contains[sub].description }@ @{ returndocs[entry].contains[sub].returned }@ @{ returndocs[entry].contains[sub].type }@ @{ returndocs[entry].contains[sub].sample}@
+
+

+{% endif %} + +{% if notes %} +{% for note in notes %} +.. note:: @{ note | convert_symbols_to_format }@ +{% endfor %} +{% endif %} + + +{% if not deprecated %} + {% if core %} + +This is a Core Module +--------------------- + +The source of this module is hosted on GitHub in the `ansible-modules-core `_ repo. + +If you believe you have found a bug in this module, and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-core `_ to see if a bug has already been filed. If not, we would be grateful if you would file one. + +Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group `_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group `_. + +Documentation updates for this module can also be edited directly by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree. + +This is a "core" ansible module, which means it will receive slightly higher priority for all requests than those in the "extras" repos. + + {% else %} + +This is an Extras Module +------------------------ + +This source of this module is hosted on GitHub in the `ansible-modules-extras `_ repo. + +If you believe you have found a bug in this module, and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-extras `_ to see if a bug has already been filed. If not, we would be grateful if you would file one. + +Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group `_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group `_. + +Documentation updates for this module can also be edited directly by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree. + +Note that this module is designated a "extras" module. Non-core modules are still fully usable, but may receive slightly lower response rates for issues and pull requests. +Popular "extras" modules may be promoted to core modules over time. + + {% endif %} +{% endif %} + +For help in developing on modules, should you be so inclined, please read :doc:`community`, :doc:`developing_test_pr` and :doc:`developing_modules`. + + diff --git a/v1/hacking/test-module b/v1/hacking/test-module new file mode 100755 index 00000000000..c226f32e889 --- /dev/null +++ b/v1/hacking/test-module @@ -0,0 +1,193 @@ +#!/usr/bin/env python + +# (c) 2012, Michael DeHaan +# +# This file is part of Ansible +# +# Ansible is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# Ansible is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Ansible. If not, see . +# + +# this script is for testing modules without running through the +# entire guts of ansible, and is very helpful for when developing +# modules +# +# example: +# test-module -m ../library/commands/command -a "/bin/sleep 3" +# test-module -m ../library/system/service -a "name=httpd ensure=restarted" +# test-module -m ../library/system/service -a "name=httpd ensure=restarted" --debugger /usr/bin/pdb +# test-modulr -m ../library/file/lineinfile -a "dest=/etc/exports line='/srv/home hostname1(rw,sync)'" --check + +import sys +import base64 +import os +import subprocess +import traceback +import optparse +import ansible.utils as utils +import ansible.module_common as module_common +import ansible.constants as C + +try: + import json +except ImportError: + import simplejson as json + +def parse(): + """parse command line + + :return : (options, args)""" + parser = optparse.OptionParser() + + parser.usage = "%prog -[options] (-h for help)" + + parser.add_option('-m', '--module-path', dest='module_path', + help="REQUIRED: full path of module source to execute") + parser.add_option('-a', '--args', dest='module_args', default="", + help="module argument string") + parser.add_option('-D', '--debugger', dest='debugger', + help="path to python debugger (e.g. /usr/bin/pdb)") + parser.add_option('-I', '--interpreter', dest='interpreter', + help="path to interpreter to use for this module (e.g. ansible_python_interpreter=/usr/bin/python)", + metavar='INTERPRETER_TYPE=INTERPRETER_PATH') + parser.add_option('-c', '--check', dest='check', action='store_true', + help="run the module in check mode") + options, args = parser.parse_args() + if not options.module_path: + parser.print_help() + sys.exit(1) + else: + return options, args + +def write_argsfile(argstring, json=False): + """ Write args to a file for old-style module's use. """ + argspath = os.path.expanduser("~/.ansible_test_module_arguments") + argsfile = open(argspath, 'w') + if json: + args = utils.parse_kv(argstring) + argstring = utils.jsonify(args) + argsfile.write(argstring) + argsfile.close() + return argspath + +def boilerplate_module(modfile, args, interpreter, check): + """ simulate what ansible does with new style modules """ + + #module_fh = open(modfile) + #module_data = module_fh.read() + #module_fh.close() + + replacer = module_common.ModuleReplacer() + + #included_boilerplate = module_data.find(module_common.REPLACER) != -1 or module_data.find("import ansible.module_utils") != -1 + + complex_args = {} + if args.startswith("@"): + # Argument is a YAML file (JSON is a subset of YAML) + complex_args = utils.combine_vars(complex_args, utils.parse_yaml_from_file(args[1:])) + args='' + elif args.startswith("{"): + # Argument is a YAML document (not a file) + complex_args = utils.combine_vars(complex_args, utils.parse_yaml(args)) + args='' + + inject = {} + if interpreter: + if '=' not in interpreter: + print 'interpreter must by in the form of ansible_python_interpreter=/usr/bin/python' + sys.exit(1) + interpreter_type, interpreter_path = interpreter.split('=') + if not interpreter_type.startswith('ansible_'): + interpreter_type = 'ansible_%s' % interpreter_type + if not interpreter_type.endswith('_interpreter'): + interpreter_type = '%s_interpreter' % interpreter_type + inject[interpreter_type] = interpreter_path + + if check: + complex_args['CHECKMODE'] = True + + (module_data, module_style, shebang) = replacer.modify_module( + modfile, + complex_args, + args, + inject + ) + + modfile2_path = os.path.expanduser("~/.ansible_module_generated") + print "* including generated source, if any, saving to: %s" % modfile2_path + print "* this may offset any line numbers in tracebacks/debuggers!" + modfile2 = open(modfile2_path, 'w') + modfile2.write(module_data) + modfile2.close() + modfile = modfile2_path + + return (modfile2_path, module_style) + +def runtest( modfile, argspath): + """Test run a module, piping it's output for reporting.""" + + os.system("chmod +x %s" % modfile) + + invoke = "%s" % (modfile) + if argspath is not None: + invoke = "%s %s" % (modfile, argspath) + + cmd = subprocess.Popen(invoke, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE) + (out, err) = cmd.communicate() + + try: + print "***********************************" + print "RAW OUTPUT" + print out + print err + results = utils.parse_json(out) + except: + print "***********************************" + print "INVALID OUTPUT FORMAT" + print out + traceback.print_exc() + sys.exit(1) + + print "***********************************" + print "PARSED OUTPUT" + print utils.jsonify(results,format=True) + +def rundebug(debugger, modfile, argspath): + """Run interactively with console debugger.""" + + if argspath is not None: + subprocess.call("%s %s %s" % (debugger, modfile, argspath), shell=True) + else: + subprocess.call("%s %s" % (debugger, modfile), shell=True) + +def main(): + + options, args = parse() + (modfile, module_style) = boilerplate_module(options.module_path, options.module_args, options.interpreter, options.check) + + argspath=None + if module_style != 'new': + if module_style == 'non_native_want_json': + argspath = write_argsfile(options.module_args, json=True) + elif module_style == 'old': + argspath = write_argsfile(options.module_args, json=False) + else: + raise Exception("internal error, unexpected module style: %s" % module_style) + if options.debugger: + rundebug(options.debugger, modfile, argspath) + else: + runtest(modfile, argspath) + +if __name__ == "__main__": + main() + diff --git a/v1/hacking/update.sh b/v1/hacking/update.sh new file mode 100755 index 00000000000..5979dd0ab2b --- /dev/null +++ b/v1/hacking/update.sh @@ -0,0 +1,3 @@ +#!/bin/sh +git pull --rebase +git submodule update --init --recursive