@@ -33,7 +33,7 @@ ASCII2MAN = @echo "ERROR: rst2man from docutils command is not installed but is

 endif

 PYTHON=python

-GENERATE_CLI = $(PYTHON) docs/bin/generate_man.py

+GENERATE_CLI = hacking/build-ansible.py generate-man

 SITELIB = $(shell $(PYTHON) -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")

deleted file mode 100755

@@ -1,74 +0,0 @@

-#!/usr/bin/env python

-

-import optparse

-import os

-import sys

-import yaml

-

-from jinja2 import Environment, FileSystemLoader

-from ansible.module_utils._text import to_bytes

-from ansible.utils._build_helpers import update_file_if_different

-

-DEFAULT_TEMPLATE_FILE = 'config.rst.j2'

-

-

-def generate_parser():

-    p = optparse.OptionParser(

-        version='%prog 1.0',

-        usage='usage: %prog [options]',

-        description='Generate module documentation from metadata',

-    )

-    p.add_option("-t", "--template-file", action="store", dest="template_file", default=DEFAULT_TEMPLATE_FILE, help="directory containing Jinja2 templates")

-    p.add_option("-o", "--output-dir", action="store", dest="output_dir", default='/tmp/', help="Output directory for rst files")

-    p.add_option("-d", "--docs-source", action="store", dest="docs", default=None, help="Source for attribute docs")

-

-    (options, args) = p.parse_args()

-

-    return p

-

-

-def fix_description(config_options):

-    '''some descriptions are strings, some are lists. workaround it...'''

-

-    for config_key in config_options:

-        description = config_options[config_key].get('description', [])

-        if isinstance(description, list):

-            desc_list = description

-        else:

-            desc_list = [description]

-        config_options[config_key]['description'] = desc_list

-    return config_options

-

-

-def main(args):

-

-    parser = generate_parser()

-    (options, args) = parser.parse_args()

-

-    output_dir = os.path.abspath(options.output_dir)

-    template_file_full_path = os.path.abspath(options.template_file)

-    template_file = os.path.basename(template_file_full_path)

-    template_dir = os.path.dirname(os.path.abspath(template_file_full_path))

-

-    if options.docs:

-        with open(options.docs) as f:

-            docs = yaml.safe_load(f)

-    else:

-        docs = {}

-

-    config_options = docs

-    config_options = fix_description(config_options)

-

-    env = Environment(loader=FileSystemLoader(template_dir), trim_blocks=True,)

-    template = env.get_template(template_file)

-    output_name = os.path.join(output_dir, template_file.replace('.j2', ''))

-    temp_vars = {'config_options': config_options}

-

-    data = to_bytes(template.render(temp_vars))

-    update_file_if_different(output_name, data)

-

-    return 0

-

-

-if __name__ == '__main__':

-    sys.exit(main(sys.argv[:]))

deleted file mode 100755

@@ -1,84 +0,0 @@

-#!/usr/bin/env python

-

-import optparse

-import re

-from distutils.version import LooseVersion

-

-import jinja2

-import yaml

-from jinja2 import Environment, FileSystemLoader

-

-from ansible.module_utils._text import to_bytes

-from ansible.playbook import Play

-from ansible.playbook.block import Block

-from ansible.playbook.role import Role

-from ansible.playbook.task import Task

-from ansible.utils._build_helpers import update_file_if_different

-

-template_file = 'playbooks_keywords.rst.j2'

-oblist = {}

-clist = []

-class_list = [Play, Role, Block, Task]

-

-p = optparse.OptionParser(

-    version='%prog 1.0',

-    usage='usage: %prog [options]',

-    description='Generate playbook keyword documentation from code and descriptions',

-)

-p.add_option("-T", "--template-dir", action="store", dest="template_dir", default="../templates", help="directory containing Jinja2 templates")

-p.add_option("-o", "--output-dir", action="store", dest="output_dir", default='/tmp/', help="Output directory for rst files")

-p.add_option("-d", "--docs-source", action="store", dest="docs", default=None, help="Source for attribute docs")

-

-(options, args) = p.parse_args()

-

-for aclass in class_list:

-    aobj = aclass()

-    name = type(aobj).__name__

-

-    if options.docs:

-        with open(options.docs) as f:

-            docs = yaml.safe_load(f)

-    else:

-        docs = {}

-

-    # build ordered list to loop over and dict with attributes

-    clist.append(name)

-    oblist[name] = dict((x, aobj.__dict__['_attributes'][x]) for x in aobj.__dict__['_attributes'] if 'private' not in x or not x.private)

-

-    # pick up docs if they exist

-    for a in oblist[name]:

-        if a in docs:

-            oblist[name][a] = docs[a]

-        else:

-            # check if there is an alias, otherwise undocumented

-            alias = getattr(getattr(aobj, '_%s' % a), 'alias', None)

-            if alias and alias in docs:

-                oblist[name][alias] = docs[alias]

-                del oblist[name][a]

-            else:

-                oblist[name][a] = ' UNDOCUMENTED!! '

-

-    # loop is really with_ for users

-    if name == 'Task':

-        oblist[name]['with_<lookup_plugin>'] = 'The same as ``loop`` but magically adds the output of any lookup plugin to generate the item list.'

-

-    # local_action is implicit with action

-    if 'action' in oblist[name]:

-        oblist[name]['local_action'] = 'Same as action but also implies ``delegate_to: localhost``'

-

-    # remove unusable (used to be private?)

-    for nouse in ('loop_args', 'loop_with'):

-        if nouse in oblist[name]:

-            del oblist[name][nouse]

-

-env = Environment(loader=FileSystemLoader(options.template_dir), trim_blocks=True,)

-template = env.get_template(template_file)

-outputname = options.output_dir + template_file.replace('.j2', '')

-tempvars = {'oblist': oblist, 'clist': clist}

-

-keyword_page = template.render(tempvars)

-if LooseVersion(jinja2.__version__) < LooseVersion('2.10'):

-    # jinja2 < 2.10's indent filter indents blank lines.  Cleanup

-    keyword_page = re.sub(' +\n', '\n', keyword_page)

-

-update_file_if_different(outputname, to_bytes(keyword_page))

deleted file mode 100755

@@ -1,290 +0,0 @@

-#!/usr/bin/env python

-

-import argparse

-import os

-import sys

-

-from jinja2 import Environment, FileSystemLoader

-

-from ansible.module_utils._text import to_bytes

-from ansible.utils._build_helpers import update_file_if_different

-

-

-def generate_parser():

-    p = argparse.ArgumentParser(

-        description='Generate cli documentation from cli docstrings',

-    )

-

-    p.add_argument("-t", "--template-file", action="store", dest="template_file", default="../templates/man.j2", help="path to jinja2 template")

-    p.add_argument("-o", "--output-dir", action="store", dest="output_dir", default='/tmp/', help="Output directory for rst files")

-    p.add_argument("-f", "--output-format", action="store", dest="output_format", default='man', help="Output format for docs (the default 'man' or 'rst')")

-    p.add_argument('args', help='CLI module(s)', metavar='module', nargs='*')

-    return p

-

-

-# from https://www.python.org/dev/peps/pep-0257/

-def trim_docstring(docstring):

-    if not docstring:

-        return ''

-    # Convert tabs to spaces (following the normal Python rules)

-    # and split into a list of lines:

-    lines = docstring.expandtabs().splitlines()

-    # Determine minimum indentation (first line doesn't count):

-    indent = sys.maxsize

-    for line in lines[1:]:

-        stripped = line.lstrip()

-        if stripped:

-            indent = min(indent, len(line) - len(stripped))

-    # Remove indentation (first line is special):

-    trimmed = [lines[0].strip()]

-    if indent < sys.maxsize:

-        for line in lines[1:]:

-            trimmed.append(line[indent:].rstrip())

-    # Strip off trailing and leading blank lines:

-    while trimmed and not trimmed[-1]:

-        trimmed.pop()

-    while trimmed and not trimmed[0]:

-        trimmed.pop(0)

-    # Return a single string:

-    return '\n'.join(trimmed)

-

-

-def get_options(optlist):

-    ''' get actual options '''

-

-    opts = []

-    for opt in optlist:

-        res = {

-            'desc': opt.help,

-            'options': opt.option_strings

-        }

-        if isinstance(opt, argparse._StoreAction):

-            res['arg'] = opt.dest.upper()

-        elif not res['options']:

-            continue

-        opts.append(res)

-

-    return opts

-

-

-def dedupe_groups(parser):

-    action_groups = []

-    for action_group in parser._action_groups:

-        found = False

-        for a in action_groups:

-            if a._actions == action_group._actions:

-                found = True

-                break

-        if not found:

-            action_groups.append(action_group)

-    return action_groups

-

-

-def get_option_groups(option_parser):

-    groups = []

-    for action_group in dedupe_groups(option_parser)[1:]:

-        group_info = {}

-        group_info['desc'] = action_group.description

-        group_info['options'] = action_group._actions

-        group_info['group_obj'] = action_group

-        groups.append(group_info)

-    return groups

-

-

-def opt_doc_list(parser):

-    ''' iterate over options lists '''

-

-    results = []

-    for option_group in dedupe_groups(parser)[1:]:

-        results.extend(get_options(option_group._actions))

-

-    results.extend(get_options(parser._actions))

-

-    return results

-

-

-# def opts_docs(cli, name):

-def opts_docs(cli_class_name, cli_module_name):

-    ''' generate doc structure from options '''

-

-    cli_name = 'ansible-%s' % cli_module_name

-    if cli_module_name == 'adhoc':

-        cli_name = 'ansible'

-

-    # WIth no action/subcommand

-    # shared opts set

-    # instantiate each cli and ask its options

-    cli_klass = getattr(__import__("ansible.cli.%s" % cli_module_name,

-                                   fromlist=[cli_class_name]), cli_class_name)

-    cli = cli_klass([cli_name])

-

-    # parse the common options

-    try:

-        cli.init_parser()

-    except Exception:

-        pass

-

-    # base/common cli info

-    docs = {

-        'cli': cli_module_name,

-        'cli_name': cli_name,

-        'usage': cli.parser.format_usage(),

-        'short_desc': cli.parser.description,

-        'long_desc': trim_docstring(cli.__doc__),

-        'actions': {},

-        'content_depth': 2,

-    }

-    option_info = {'option_names': [],

-                   'options': [],

-                   'groups': []}

-

-    for extras in ('ARGUMENTS'):

-        if hasattr(cli, extras):

-            docs[extras.lower()] = getattr(cli, extras)

-

-    common_opts = opt_doc_list(cli.parser)

-    groups_info = get_option_groups(cli.parser)

-    shared_opt_names = []

-    for opt in common_opts:

-        shared_opt_names.extend(opt.get('options', []))

-

-    option_info['options'] = common_opts

-    option_info['option_names'] = shared_opt_names

-

-    option_info['groups'].extend(groups_info)

-

-    docs.update(option_info)

-

-    # now for each action/subcommand

-    # force populate parser with per action options

-

-    def get_actions(parser, docs):

-        # use class attrs not the attrs on a instance (not that it matters here...)

-        try:

-            subparser = parser._subparsers._group_actions[0].choices

-        except AttributeError:

-            subparser = {}

-

-        depth = 0

-

-        for action, parser in subparser.items():

-            action_info = {'option_names': [],

-                           'options': [],

-                           'actions': {}}

-            # docs['actions'][action] = {}

-            # docs['actions'][action]['name'] = action

-            action_info['name'] = action

-            action_info['desc'] = trim_docstring(getattr(cli, 'execute_%s' % action).__doc__)

-

-            # docs['actions'][action]['desc'] = getattr(cli, 'execute_%s' % action).__doc__.strip()

-            action_doc_list = opt_doc_list(parser)

-

-            uncommon_options = []

-            for action_doc in action_doc_list:

-                # uncommon_options = []

-

-                option_aliases = action_doc.get('options', [])

-                for option_alias in option_aliases:

-

-                    if option_alias in shared_opt_names:

-                        continue

-

-                    # TODO: use set

-                    if option_alias not in action_info['option_names']:

-                        action_info['option_names'].append(option_alias)

-

-                    if action_doc in action_info['options']:

-                        continue

-

-                    uncommon_options.append(action_doc)

-

-                action_info['options'] = uncommon_options

-

-            depth = 1 + get_actions(parser, action_info)

-

-            docs['actions'][action] = action_info

-

-        return depth

-

-    action_depth = get_actions(cli.parser, docs)

-    docs['content_depth'] = action_depth + 1

-

-    docs['options'] = opt_doc_list(cli.parser)

-    return docs

-

-

-if __name__ == '__main__':

-

-    parser = generate_parser()

-

-    options = parser.parse_args()

-

-    template_file = options.template_file

-    template_path = os.path.expanduser(template_file)

-    template_dir = os.path.abspath(os.path.dirname(template_path))

-    template_basename = os.path.basename(template_file)

-

-    output_dir = os.path.abspath(options.output_dir)

-    output_format = options.output_format

-

-    cli_modules = options.args

-

-    # various cli parsing things checks sys.argv if the 'args' that are passed in are []

-    # so just remove any args so the cli modules dont try to parse them resulting in warnings

-    sys.argv = [sys.argv[0]]

-    # need to be in right dir

-    os.chdir(os.path.dirname(__file__))

-

-    allvars = {}

-    output = {}

-    cli_list = []

-    cli_bin_name_list = []

-

-    # for binary in os.listdir('../../lib/ansible/cli'):

-    for cli_module_name in cli_modules:

-        binary = os.path.basename(os.path.expanduser(cli_module_name))

-

-        if not binary.endswith('.py'):

-            continue

-        elif binary == '__init__.py':

-            continue

-

-        cli_name = os.path.splitext(binary)[0]

-

-        if cli_name == 'adhoc':

-            cli_class_name = 'AdHocCLI'

-            # myclass = 'AdHocCLI'

-            output[cli_name] = 'ansible.1.rst.in'

-            cli_bin_name = 'ansible'

-        else:

-            # myclass = "%sCLI" % libname.capitalize()

-            cli_class_name = "%sCLI" % cli_name.capitalize()

-            output[cli_name] = 'ansible-%s.1.rst.in' % cli_name

-            cli_bin_name = 'ansible-%s' % cli_name

-

-        # FIXME:

-        allvars[cli_name] = opts_docs(cli_class_name, cli_name)

-        cli_bin_name_list.append(cli_bin_name)

-

-    cli_list = allvars.keys()

-

-    doc_name_formats = {'man': '%s.1.rst.in',

-                        'rst': '%s.rst'}

-

-    for cli_name in cli_list:

-

-        # template it!

-        env = Environment(loader=FileSystemLoader(template_dir))

-        template = env.get_template(template_basename)

-

-        # add rest to vars

-        tvars = allvars[cli_name]

-        tvars['cli_list'] = cli_list

-        tvars['cli_bin_name_list'] = cli_bin_name_list

-        tvars['cli'] = cli_name

-        if '-i' in tvars['options']:

-            print('uses inventory')

-

-        manpage = template.render(tvars)

-        filename = os.path.join(output_dir, doc_name_formats[output_format] % tvars['cli_name'])

-        update_file_if_different(filename, to_bytes(manpage))

deleted file mode 100755

@@ -1,815 +0,0 @@

-#!/usr/bin/env python

-# Copyright: (c) 2012, Jan-Piet Mens <jpmens () gmail.com>

-# Copyright: (c) 2012-2014, Michael DeHaan <michael@ansible.com> and others

-# Copyright: (c) 2017, Ansible Project

-

-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

-

-from __future__ import absolute_import, division, print_function

-__metaclass__ = type

-

-

-import datetime

-import glob

-import json

-import optparse

-import os

-import re

-import sys

-import warnings

-from collections import defaultdict

-from copy import deepcopy

-from distutils.version import LooseVersion

-from functools import partial

-from pprint import PrettyPrinter

-

-try:

-    from html import escape as html_escape

-except ImportError:

-    # Python-3.2 or later

-    import cgi

-

-    def html_escape(text, quote=True):

-        return cgi.escape(text, quote)

-

-import jinja2

-import yaml

-from jinja2 import Environment, FileSystemLoader

-from jinja2.runtime import Undefined

-

-from ansible.errors import AnsibleError

-from ansible.module_utils._text import to_bytes, to_text

-from ansible.module_utils.common.collections import is_sequence

-from ansible.module_utils.parsing.convert_bool import boolean

-from ansible.module_utils.six import iteritems, string_types

-from ansible.plugins.loader import fragment_loader

-from ansible.utils import plugin_docs

-from ansible.utils.display import Display

-from ansible.utils._build_helpers import update_file_if_different

-

-

-#####################################################################################

-# 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.

-TOO_OLD_TO_BE_NOTABLE = 2.3

-

-# 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\(([^)]+)\)")

-_LINK = re.compile(r"L\(([^)]+),([^)]+)\)")

-_CONST = re.compile(r"C\(([^)]+)\)")

-_RULER = re.compile(r"HORIZONTALLINE")

-

-DEPRECATED = b" (D)"

-

-pp = PrettyPrinter()

-display = Display()

-

-

-# kludge_ns gives us a kludgey way to set variables inside of loops that need to be visible outside

-# the loop.  We can get rid of this when we no longer need to build docs with less than Jinja-2.10

-# http://jinja.pocoo.org/docs/2.10/templates/#assignments

-# With Jinja-2.10 we can use jinja2's namespace feature, restoring the namespace template portion

-# of: fa5c0282a4816c4dd48e80b983ffc1e14506a1f5

-NS_MAP = {}

-

-

-def to_kludge_ns(key, value):

-    NS_MAP[key] = value

-    return ""

-

-

-def from_kludge_ns(key):

-    return NS_MAP[key]

-

-

-# The max filter was added in Jinja2-2.10.  Until we can require that version, use this

-def do_max(seq):

-    return max(seq)

-

-

-def rst_ify(text):

-    ''' convert symbols like I(this is in italics) to valid restructured text '''

-

-    try:

-        t = _ITALIC.sub(r"*\1*", text)

-        t = _BOLD.sub(r"**\1**", t)

-        t = _MODULE.sub(r":ref:`\1 <\1_module>`", t)

-        t = _LINK.sub(r"`\1 <\2>`_", t)

-        t = _URL.sub(r"\1", t)

-        t = _CONST.sub(r"``\1``", t)

-        t = _RULER.sub(r"------------", t)

-    except Exception as e:

-        raise AnsibleError("Could not process (%s) : %s" % (text, e))

-

-    return t

-

-

-def html_ify(text):

-    ''' convert symbols like I(this is in italics) to valid HTML '''

-

-    if not isinstance(text, string_types):

-        text = to_text(text)

-

-    t = html_escape(text)

-    t = _ITALIC.sub(r"<em>\1</em>", t)

-    t = _BOLD.sub(r"<b>\1</b>", t)

-    t = _MODULE.sub(r"<span class='module'>\1</span>", t)

-    t = _URL.sub(r"<a href='\1'>\1</a>", t)

-    t = _LINK.sub(r"<a href='\2'>\1</a>", t)

-    t = _CONST.sub(r"<code>\1</code>", t)

-    t = _RULER.sub(r"<hr/>", t)

-

-    return t.strip()

-

-

-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 documented_type(text):

-    ''' Convert any python type to a type for documentation '''

-

-    if isinstance(text, Undefined):

-        return '-'

-    if text == 'str':

-        return 'string'

-    if text == 'bool':

-        return 'boolean'

-    if text == 'int':

-        return 'integer'

-    if text == 'dict':

-        return 'dictionary'

-    return text

-

-

-test_list = partial(is_sequence, include_strings=False)

-

-

-def normalize_options(value):

-    """Normalize boolean option value."""

-

-    if value.get('type') == 'bool' and 'default' in value:

-        try:

-            value['default'] = boolean(value['default'], strict=True)

-        except TypeError:

-            pass

-    return value

-

-

-def write_data(text, output_dir, outputname, module=None):

-    ''' dumps module output to a file or the screen, as requested '''

-

-    if output_dir is not None:

-        if module:

-            outputname = outputname % module

-

-        if not os.path.exists(output_dir):

-            os.makedirs(output_dir)

-        fname = os.path.join(output_dir, outputname)

-        fname = fname.replace(".py", "")

-

-        try:

-            updated = update_file_if_different(fname, to_bytes(text))

-        except Exception as e:

-            display.display("while rendering %s, an error occured: %s" % (module, e))

-            raise

-        if updated:

-            display.display("rendering: %s" % module)

-    else:

-        print(text)

-

-

-IS_STDOUT_TTY = sys.stdout.isatty()

-

-

-def show_progress(progress):

-    '''Show a little process indicator.'''

-    if IS_STDOUT_TTY:

-        sys.stdout.write('\r%s\r' % ("-/|\\"[progress % 4]))

-        sys.stdout.flush()

-

-

-def get_plugin_info(module_dir, limit_to=None, verbose=False):

-    '''

-    Returns information about plugins and the categories that they belong to

-

-    :arg module_dir: file system path to the top of the plugin directory

-    :kwarg limit_to: If given, this is a list of plugin names to

-        generate information for.  All other plugins will be ignored.

-    :returns: Tuple of two dicts containing module_info, categories, and

-        aliases and a set listing deprecated modules:

-

-        :module_info: mapping of module names to information about them.  The fields of the dict are:

-

-            :path: filesystem path to the module

-            :deprecated: boolean.  True means the module is deprecated otherwise not.

-            :aliases: set of aliases to this module name

-            :metadata: The modules metadata (as recorded in the module)

-            :doc: The documentation structure for the module

-            :seealso: The list of dictionaries with references to related subjects

-            :examples: The module's examples

-            :returndocs: The module's returndocs

-

-        :categories: maps category names to a dict.  The dict contains at

-            least one key, '_modules' which contains a list of module names in

-            that category.  Any other keys in the dict are subcategories with

-            the same structure.

-

-    '''

-

-    categories = dict()

-    module_info = defaultdict(dict)

-

-    # * windows powershell modules have documentation stubs in python docstring

-    #   format (they are not executed) so skip the ps1 format files

-    # * One glob level for every module level that we're going to traverse

-    files = (

-        glob.glob("%s/*.py" % module_dir) +

-        glob.glob("%s/*/*.py" % module_dir) +

-        glob.glob("%s/*/*/*.py" % module_dir) +

-        glob.glob("%s/*/*/*/*.py" % module_dir)

-    )

-

-    module_index = 0

-    for module_path in files:

-        # Do not list __init__.py files

-        if module_path.endswith('__init__.py'):

-            continue

-

-        # Do not list blacklisted modules

-        module = os.path.splitext(os.path.basename(module_path))[0]

-        if module in plugin_docs.BLACKLIST['MODULE'] or module == 'base':

-            continue

-

-        # If requested, limit module documentation building only to passed-in

-        # modules.

-        if limit_to is not None and module.lower() not in limit_to:

-            continue

-

-        deprecated = False

-        if module.startswith("_"):

-            if os.path.islink(module_path):

-                # Handle aliases

-                source = os.path.splitext(os.path.basename(os.path.realpath(module_path)))[0]

-                module = module.replace("_", "", 1)

-                if source.startswith("_"):

-                    source = source.replace("_", "", 1)

-                aliases = module_info[source].get('aliases', set())

-                aliases.add(module)

-                aliases_deprecated = module_info[source].get('aliases_deprecated', set())

-                aliases_deprecated.add(module)

-                # In case we just created this via get()'s fallback

-                module_info[source]['aliases'] = aliases

-                module_info[source]['aliases_deprecated'] = aliases_deprecated

-                continue

-            else:

-                # Handle deprecations

-                module = module.replace("_", "", 1)

-                deprecated = True

-

-        #

-        # Regular module to process

-        #

-

-        module_index += 1

-        show_progress(module_index)

-

-        # use ansible core library to parse out doc metadata YAML and plaintext examples

-        doc, examples, returndocs, metadata = plugin_docs.get_docstring(module_path, fragment_loader, verbose=verbose)

-

-        if metadata and 'removed' in metadata.get('status', []):

-            continue

-

-        category = categories

-

-        # Start at the second directory because we don't want the "vendor"

-        mod_path_only = os.path.dirname(module_path[len(module_dir):])

-

-        # Find the subcategory for each module

-        relative_dir = mod_path_only.split('/')[1]

-        sub_category = mod_path_only[len(relative_dir) + 2:]

-

-        primary_category = ''

-        module_categories = []

-        # build up the categories that this module belongs to

-        for new_cat in mod_path_only.split('/')[1:]:

-            if new_cat not in category:

-                category[new_cat] = dict()

-                category[new_cat]['_modules'] = []

-            module_categories.append(new_cat)

-            category = category[new_cat]

-

-        category['_modules'].append(module)

-

-        # the category we will use in links (so list_of_all_plugins can point to plugins/action_plugins/*'

-        if module_categories:

-            primary_category = module_categories[0]

-

-        if not doc:

-            display.error("*** ERROR: DOCUMENTATION section missing for %s. ***" % module_path)

-            continue

-

-        if 'options' in doc and doc['options'] is None:

-            display.error("*** ERROR: DOCUMENTATION.options must be a dictionary/hash when used. ***")

-            pos = getattr(doc, "ansible_pos", None)

-            if pos is not None:

-                display.error("Module position: %s, %d, %d" % doc.ansible_pos)

-            doc['options'] = dict()

-

-        for key, opt in doc.get('options', {}).items():

-            doc['options'][key] = normalize_options(opt)

-

-        # save all the information

-        module_info[module] = {'path': module_path,

-                               'source': os.path.relpath(module_path, module_dir),

-                               'deprecated': deprecated,

-                               'aliases': module_info[module].get('aliases', set()),

-                               'aliases_deprecated': module_info[module].get('aliases_deprecated', set()),

-                               'metadata': metadata,

-                               'doc': doc,

-                               'examples': examples,

-                               'returndocs': returndocs,

-                               'categories': module_categories,

-                               'primary_category': primary_category,

-                               'sub_category': sub_category,

-                               }

-

-    # keep module tests out of becoming module docs

-    if 'test' in categories:

-        del categories['test']

-

-    return module_info, 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("-P", "--plugin-type", action="store", dest="plugin_type", default='module', help="The type of plugin (module, lookup, etc)")

-    p.add_option("-T", "--template-dir", action="append", dest="template_dir", help="directory containing Jinja2 templates")

-    p.add_option("-t", "--type", action='store', dest='type', choices=['rst'], default='rst', help="Document type")

-    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("-l", "--limit-to-modules", '--limit-to', action="store", dest="limit_to", default=None,

-                 help="Limit building module documentation to comma-separated list of plugins. Specify non-existing plugin name for no plugins.")

-    p.add_option('-V', action='version', help='Show version number and exit')

-    p.add_option('-v', '--verbose', dest='verbosity', default=0, action="count", help="verbose mode (increase number of 'v's for more)")

-    return p

-

-

-def jinja2_environment(template_dir, typ, plugin_type):

-

-    env = Environment(loader=FileSystemLoader(template_dir),

-                      variable_start_string="@{",

-                      variable_end_string="}@",

-                      trim_blocks=True)

-    env.globals['xline'] = rst_xline

-

-    # Can be removed (and template switched to use namespace) when we no longer need to build

-    # with <Jinja-2.10

-    env.globals['to_kludge_ns'] = to_kludge_ns

-    env.globals['from_kludge_ns'] = from_kludge_ns

-    if 'max' not in env.filters:

-        # Jinja < 2.10

-        env.filters['max'] = do_max