mirror of
https://github.com/ansible-collections/community.general.git
synced 2025-05-11 03:31:29 -07:00
Enable documentation in plugins
Made ansible-doc more plugin agnostic We can have docs in lookup, callback, connectionm strategy, etc Use first docstring and make pepizis happy generalized module_docs to plugin_docs documented cartesian, ssh, default, jsonfile, etc as examples changed lack of docs to warning when listing made smarter about bad docstrings better blacklisting added handling of options/config/envs/etc move blacklist to find_plugins, only need once
This commit is contained in:
Brian Coca
Brian Coca
parent
d3115ae8f3
commit
7839f70e36
18 changed files with 583 additions and 268 deletions
|
|
@ -23,14 +23,15 @@ import datetime
|
|||
import os
|
||||
import traceback
|
||||
import textwrap
|
||||
import yaml
|
||||
|
||||
from ansible.compat.six import iteritems, string_types
|
||||
|
||||
from ansible import constants as C
|
||||
from ansible.errors import AnsibleError, AnsibleOptionsError
|
||||
from ansible.plugins import module_loader, action_loader
|
||||
from ansible.plugins import module_loader, action_loader, lookup_loader, callback_loader, cache_loader, connection_loader, strategy_loader
|
||||
from ansible.cli import CLI
|
||||
from ansible.utils import module_docs
|
||||
from ansible.utils import plugin_docs
|
||||
|
||||
try:
|
||||
from __main__ import display
|
||||
|
|
@ -40,27 +41,29 @@ except ImportError:
|
|||
|
||||
|
||||
class DocCLI(CLI):
|
||||
""" Vault command line class """
|
||||
""" Doc command line class """
|
||||
|
||||
def __init__(self, args):
|
||||
|
||||
super(DocCLI, self).__init__(args)
|
||||
self.module_list = []
|
||||
self.plugin_list = set()
|
||||
|
||||
def parse(self):
|
||||
|
||||
self.parser = CLI.base_parser(
|
||||
usage='usage: %prog [options] [module...]',
|
||||
epilog='Show Ansible module documentation',
|
||||
usage='usage: %prog [options] [plugin ...]',
|
||||
epilog='Show Ansible plugin documentation',
|
||||
module_opts=True,
|
||||
)
|
||||
|
||||
self.parser.add_option("-l", "--list", action="store_true", default=False, dest='list_dir',
|
||||
help='List available modules')
|
||||
help='List available plugins')
|
||||
self.parser.add_option("-s", "--snippet", action="store_true", default=False, dest='show_snippet',
|
||||
help='Show playbook snippet for specified module(s)')
|
||||
self.parser.add_option("-a", "--all", action="store_true", default=False, dest='all_modules',
|
||||
help='Show documentation for all modules')
|
||||
help='Show playbook snippet for specified plugin(s)')
|
||||
self.parser.add_option("-a", "--all", action="store_true", default=False, dest='all_plugins',
|
||||
help='Show documentation for all plugins')
|
||||
self.parser.add_option("-t", "--type", action="store", default='module', dest='type', type='choice',
|
||||
help='Choose which plugin type', choices=['module','cache', 'connection', 'callback', 'lookup', 'strategy'])
|
||||
|
||||
super(DocCLI, self).parse()
|
||||
|
||||
|
|
@ -70,76 +73,85 @@ class DocCLI(CLI):
|
|||
|
||||
super(DocCLI, self).run()
|
||||
|
||||
plugin_type = self.options.type
|
||||
|
||||
# choose plugin type
|
||||
if plugin_type == 'cache':
|
||||
loader = cache_loader
|
||||
elif plugin_type == 'callback':
|
||||
loader = callback_loader
|
||||
elif plugin_type == 'connection':
|
||||
loader = connection_loader
|
||||
elif plugin_type == 'lookup':
|
||||
loader = lookup_loader
|
||||
elif plugin_type == 'strategy':
|
||||
loader = strategy_loader
|
||||
else:
|
||||
loader = module_loader
|
||||
|
||||
# add to plugin path from command line
|
||||
if self.options.module_path is not None:
|
||||
for i in self.options.module_path.split(os.pathsep):
|
||||
module_loader.add_directory(i)
|
||||
loader.add_directory(i)
|
||||
|
||||
# list modules
|
||||
# list plugins for type
|
||||
if self.options.list_dir:
|
||||
paths = module_loader._get_paths()
|
||||
paths = loader._get_paths()
|
||||
for path in paths:
|
||||
self.find_modules(path)
|
||||
self.find_plugins(path, plugin_type)
|
||||
|
||||
self.pager(self.get_module_list_text())
|
||||
self.pager(self.get_plugin_list_text(loader))
|
||||
return 0
|
||||
|
||||
# process all modules
|
||||
if self.options.all_modules:
|
||||
paths = module_loader._get_paths()
|
||||
# process all plugins of type
|
||||
if self.options.all_plugins:
|
||||
paths = loader._get_paths()
|
||||
for path in paths:
|
||||
self.find_modules(path)
|
||||
self.args = sorted(set(self.module_list) - module_docs.BLACKLIST_MODULES)
|
||||
self.find_plugins(path, plugin_type)
|
||||
|
||||
if len(self.args) == 0:
|
||||
raise AnsibleOptionsError("Incorrect options passed")
|
||||
|
||||
# process command line module list
|
||||
# process command line list
|
||||
text = ''
|
||||
for module in self.args:
|
||||
for plugin in self.args:
|
||||
|
||||
try:
|
||||
# if the module lives in a non-python file (eg, win_X.ps1), require the corresponding python file for docs
|
||||
filename = module_loader.find_plugin(module, mod_type='.py', ignore_deprecated=True)
|
||||
# if the plugin lives in a non-python file (eg, win_X.ps1), require the corresponding python file for docs
|
||||
filename = loader.find_plugin(plugin, mod_type='.py', ignore_deprecated=True)
|
||||
if filename is None:
|
||||
display.warning("module %s not found in %s\n" % (module, DocCLI.print_paths(module_loader)))
|
||||
display.warning("%s %s not found in %s\n" % (plugin_type, plugin, DocCLI.print_paths(loader)))
|
||||
continue
|
||||
|
||||
if any(filename.endswith(x) for x in C.BLACKLIST_EXTS):
|
||||
continue
|
||||
|
||||
try:
|
||||
doc, plainexamples, returndocs, metadata = module_docs.get_docstring(filename, verbose=(self.options.verbosity > 0))
|
||||
doc, plainexamples, returndocs, metadata = plugin_docs.get_docstring(filename, verbose=(self.options.verbosity > 0))
|
||||
except:
|
||||
display.vvv(traceback.format_exc())
|
||||
display.error("module %s has a documentation error formatting or is missing documentation\nTo see exact traceback use -vvv" % module)
|
||||
display.error("%s %s has a documentation error formatting or is missing documentation." % (plugin_type, plugin))
|
||||
continue
|
||||
|
||||
if doc is not None:
|
||||
|
||||
# is there corresponding action plugin?
|
||||
if module in action_loader:
|
||||
doc['action'] = True
|
||||
else:
|
||||
doc['action'] = False
|
||||
|
||||
all_keys = []
|
||||
for (k,v) in iteritems(doc['options']):
|
||||
all_keys.append(k)
|
||||
all_keys = sorted(all_keys)
|
||||
doc['option_keys'] = all_keys
|
||||
|
||||
doc['filename'] = filename
|
||||
doc['docuri'] = doc['module'].replace('_', '-')
|
||||
doc['now_date'] = datetime.date.today().strftime('%Y-%m-%d')
|
||||
# assign from other sections
|
||||
doc['plainexamples'] = plainexamples
|
||||
doc['returndocs'] = returndocs
|
||||
doc['metadata'] = metadata
|
||||
if 'metadata_version' in doc['metadata']:
|
||||
del doc['metadata']['metadata_version']
|
||||
if 'version' in doc['metadata']:
|
||||
del doc['metadata']['metadata_version']
|
||||
|
||||
if self.options.show_snippet:
|
||||
# generate extra data
|
||||
if plugin_type == 'module':
|
||||
# is there corresponding action plugin?
|
||||
if plugin in action_loader:
|
||||
doc['action'] = True
|
||||
else:
|
||||
doc['action'] = False
|
||||
doc['filename'] = filename
|
||||
doc['now_date'] = datetime.date.today().strftime('%Y-%m-%d')
|
||||
doc['docuri'] = doc[plugin_type].replace('_', '-')
|
||||
|
||||
if self.options.show_snippet and plugin_type == 'module':
|
||||
text += self.get_snippet_text(doc)
|
||||
else:
|
||||
text += self.get_man_text(doc)
|
||||
|
|
@ -149,47 +161,56 @@ class DocCLI(CLI):
|
|||
raise AnsibleError("Parsing produced an empty object.")
|
||||
except Exception as e:
|
||||
display.vvv(traceback.format_exc())
|
||||
raise AnsibleError("module %s missing documentation (or could not parse documentation): %s\n" % (module, str(e)))
|
||||
raise AnsibleError("%s %s missing documentation (or could not parse documentation): %s\n" % (plugin_type, plugin, str(e)))
|
||||
|
||||
if text:
|
||||
self.pager(text)
|
||||
return 0
|
||||
|
||||
def find_modules(self, path):
|
||||
for module in os.listdir(path):
|
||||
full_path = '/'.join([path, module])
|
||||
def find_plugins(self, path, ptype):
|
||||
|
||||
if module.startswith('.'):
|
||||
display.vvvv("Searching %s for plugins" % path)
|
||||
|
||||
if not os.path.exists(path):
|
||||
display.vvvv("%s does not exist" % path)
|
||||
return
|
||||
|
||||
bkey = ptype.upper()
|
||||
for plugin in os.listdir(path):
|
||||
display.vvvv("Found %s" % plugin)
|
||||
full_path = '/'.join([path, plugin])
|
||||
|
||||
if plugin.startswith('.'):
|
||||
continue
|
||||
elif os.path.isdir(full_path):
|
||||
continue
|
||||
elif any(module.endswith(x) for x in C.BLACKLIST_EXTS):
|
||||
elif any(plugin.endswith(x) for x in C.BLACKLIST_EXTS):
|
||||
continue
|
||||
elif module.startswith('__'):
|
||||
elif plugin.startswith('__'):
|
||||
continue
|
||||
elif module in C.IGNORE_FILES:
|
||||
elif plugin in C.IGNORE_FILES:
|
||||
continue
|
||||
elif module.startswith('_'):
|
||||
elif plugin .startswith('_'):
|
||||
if os.path.islink(full_path): # avoids aliases
|
||||
continue
|
||||
|
||||
module = os.path.splitext(module)[0] # removes the extension
|
||||
module = module.lstrip('_') # remove underscore from deprecated modules
|
||||
self.module_list.append(module)
|
||||
plugin = os.path.splitext(plugin)[0] # removes the extension
|
||||
plugin = plugin.lstrip('_') # remove underscore from deprecated plugins
|
||||
|
||||
def get_module_list_text(self):
|
||||
if plugin not in plugin_docs.BLACKLIST.get(bkey, ()):
|
||||
self.plugin_list.add(plugin)
|
||||
display.vvvv("Added %s" % plugin)
|
||||
|
||||
def get_plugin_list_text(self, loader):
|
||||
columns = display.columns
|
||||
displace = max(len(x) for x in self.module_list)
|
||||
displace = max(len(x) for x in self.plugin_list)
|
||||
linelimit = columns - displace - 5
|
||||
text = []
|
||||
deprecated = []
|
||||
for module in sorted(set(self.module_list)):
|
||||
|
||||
if module in module_docs.BLACKLIST_MODULES:
|
||||
continue
|
||||
for plugin in sorted(self.plugin_list):
|
||||
|
||||
# if the module lives in a non-python file (eg, win_X.ps1), require the corresponding python file for docs
|
||||
filename = module_loader.find_plugin(module, mod_type='.py', ignore_deprecated=True)
|
||||
filename = loader.find_plugin(plugin, mod_type='.py', ignore_deprecated=True)
|
||||
|
||||
if filename is None:
|
||||
continue
|
||||
|
|
@ -199,17 +220,23 @@ class DocCLI(CLI):
|
|||
continue
|
||||
|
||||
try:
|
||||
doc, plainexamples, returndocs, metadata = module_docs.get_docstring(filename)
|
||||
desc = self.tty_ify(doc.get('short_description', '?')).strip()
|
||||
if len(desc) > linelimit:
|
||||
desc = desc[:linelimit] + '...'
|
||||
|
||||
if module.startswith('_'): # Handle deprecated
|
||||
deprecated.append("%-*s %-*.*s" % (displace, module[1:], linelimit, len(desc), desc))
|
||||
else:
|
||||
text.append("%-*s %-*.*s" % (displace, module, linelimit, len(desc), desc))
|
||||
doc, plainexamples, returndocs, metadata = plugin_docs.get_docstring(filename)
|
||||
except:
|
||||
raise AnsibleError("module %s has a documentation error formatting or is missing documentation\n" % module)
|
||||
display.warning("%s has a documentation formatting error" % plugin)
|
||||
|
||||
if not doc:
|
||||
desc = 'UNDOCUMENTED'
|
||||
display.warning("%s parsing did not produce documentation." % plugin)
|
||||
else:
|
||||
desc = self.tty_ify(doc.get('short_description', '?')).strip()
|
||||
|
||||
if len(desc) > linelimit:
|
||||
desc = desc[:linelimit] + '...'
|
||||
|
||||
if plugin.startswith('_'): # Handle deprecated
|
||||
deprecated.append("%-*s %-*.*s" % (displace, plugin[1:], linelimit, len(desc), desc))
|
||||
else:
|
||||
text.append("%-*s %-*.*s" % (displace, plugin, linelimit, len(desc), desc))
|
||||
|
||||
if len(deprecated) > 0:
|
||||
text.append("\nDEPRECATED:")
|
||||
|
|
@ -253,34 +280,10 @@ class DocCLI(CLI):
|
|||
|
||||
return "\n".join(text)
|
||||
|
||||
def get_man_text(self, doc):
|
||||
def add_fields(self, text, fields, limit, opt_indent):
|
||||
|
||||
opt_indent=" "
|
||||
text = []
|
||||
text.append("> %s (%s)\n" % (doc['module'].upper(), doc['filename']))
|
||||
pad = display.columns * 0.20
|
||||
limit = max(display.columns - int(pad), 70)
|
||||
|
||||
if isinstance(doc['description'], list):
|
||||
desc = " ".join(doc['description'])
|
||||
else:
|
||||
desc = doc['description']
|
||||
|
||||
text.append("%s\n" % textwrap.fill(CLI.tty_ify(desc), limit, initial_indent=" ", subsequent_indent=" "))
|
||||
|
||||
# FUTURE: move deprecation to metadata-only
|
||||
|
||||
if 'deprecated' in doc and doc['deprecated'] is not None and len(doc['deprecated']) > 0:
|
||||
text.append("DEPRECATED: \n%s\n" % doc['deprecated'])
|
||||
|
||||
if 'action' in doc and doc['action']:
|
||||
text.append(" * note: %s\n" % "This module has a corresponding action plugin.")
|
||||
|
||||
if 'option_keys' in doc and len(doc['option_keys']) > 0:
|
||||
text.append("Options (= is mandatory):\n")
|
||||
|
||||
for o in sorted(doc['option_keys']):
|
||||
opt = doc['options'][o]
|
||||
for o in sorted(fields):
|
||||
opt = fields[o]
|
||||
|
||||
required = opt.get('required', False)
|
||||
if not isinstance(required, bool):
|
||||
|
|
@ -306,6 +309,45 @@ class DocCLI(CLI):
|
|||
default = "[Default: " + str(opt.get('default', '(null)')) + "]"
|
||||
text.append(textwrap.fill(CLI.tty_ify(choices + default), limit, initial_indent=opt_indent, subsequent_indent=opt_indent))
|
||||
|
||||
for conf in ('config', 'env_vars', 'host_vars'):
|
||||
if conf in opt:
|
||||
text.append(textwrap.fill(CLI.tty_ify("%s: " % conf), limit, initial_indent=opt_indent, subsequent_indent=opt_indent))
|
||||
for entry in opt[conf]:
|
||||
if isinstance(entry, dict):
|
||||
pre = " -"
|
||||
for key in entry:
|
||||
text.append(textwrap.fill(CLI.tty_ify("%s %s: %s" % (pre, key, entry[key])),
|
||||
limit, initial_indent=opt_indent, subsequent_indent=opt_indent))
|
||||
pre = " "
|
||||
else:
|
||||
text.append(textwrap.fill(CLI.tty_ify(" - %s" % entry), limit, initial_indent=opt_indent, subsequent_indent=opt_indent))
|
||||
|
||||
def get_man_text(self, doc):
|
||||
|
||||
opt_indent=" "
|
||||
text = []
|
||||
text.append("> %s (%s)\n" % (doc[self.options.type].upper(), doc['filename']))
|
||||
pad = display.columns * 0.20
|
||||
limit = max(display.columns - int(pad), 70)
|
||||
|
||||
if isinstance(doc['description'], list):
|
||||
desc = " ".join(doc['description'])
|
||||
else:
|
||||
desc = doc['description']
|
||||
|
||||
text.append("%s\n" % textwrap.fill(CLI.tty_ify(desc), limit, initial_indent=" ", subsequent_indent=" "))
|
||||
|
||||
if 'deprecated' in doc and doc['deprecated'] is not None and len(doc['deprecated']) > 0:
|
||||
text.append("DEPRECATED: \n%s\n" % doc['deprecated'])
|
||||
|
||||
if 'action' in doc and doc['action']:
|
||||
text.append(" * note: %s\n" % "This module has a corresponding action plugin.")
|
||||
|
||||
if 'options' in doc and doc['options']:
|
||||
text.append("Options (= is mandatory):\n")
|
||||
self.add_fields(text, doc['options'], limit, opt_indent)
|
||||
text.append('')
|
||||
|
||||
if 'notes' in doc and doc['notes'] and len(doc['notes']) > 0:
|
||||
text.append("Notes:")
|
||||
for note in doc['notes']:
|
||||
|
|
@ -321,11 +363,18 @@ class DocCLI(CLI):
|
|||
text.append("%s\n" % (ex['code']))
|
||||
|
||||
if 'plainexamples' in doc and doc['plainexamples'] is not None:
|
||||
text.append("EXAMPLES:")
|
||||
text.append(doc['plainexamples'])
|
||||
text.append("EXAMPLES:\n")
|
||||
if isinstance(doc['plainexamples'], string_types):
|
||||
text.append(doc['plainexamples'])
|
||||
else:
|
||||
text.append(yaml.dump(doc['plainexamples'], indent=2, default_flow_style=False))
|
||||
|
||||
if 'returndocs' in doc and doc['returndocs'] is not None:
|
||||
text.append("RETURN VALUES:")
|
||||
text.append(doc['returndocs'])
|
||||
text.append("RETURN VALUES:\n")
|
||||
if isinstance(doc['returndocs'], string_types):
|
||||
text.append(doc['returndocs'])
|
||||
else:
|
||||
text.append(yaml.dump(doc['returndocs'], indent=2, default_flow_style=False))
|
||||
text.append('')
|
||||
|
||||
maintainers = set()
|
||||
|
|
@ -344,7 +393,7 @@ class DocCLI(CLI):
|
|||
text.append('MAINTAINERS: ' + ', '.join(maintainers))
|
||||
text.append('')
|
||||
|
||||
if doc['metadata'] and isinstance(doc['metadata'], dict):
|
||||
if 'metadata' in doc and doc['metadata']:
|
||||
text.append("METADATA:")
|
||||
for k in doc['metadata']:
|
||||
if isinstance(k, list):
|
||||
|
|
@ -352,5 +401,4 @@ class DocCLI(CLI):
|
|||
else:
|
||||
text.append("\t%s: %s" % (k.capitalize(), doc['metadata'][k]))
|
||||
text.append('')
|
||||
|
||||
return "\n".join(text)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue