1# Copyright: (c) 2014, James Tanner <tanner.jc@gmail.com> 2# Copyright: (c) 2018, Ansible Project 3# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) 4 5from __future__ import (absolute_import, division, print_function) 6__metaclass__ = type 7 8import datetime 9import json 10import os 11import re 12import textwrap 13import traceback 14import yaml 15 16import ansible.plugins.loader as plugin_loader 17 18from ansible import constants as C 19from ansible import context 20from ansible.cli import CLI 21from ansible.cli.arguments import option_helpers as opt_help 22from ansible.collections.list import list_collection_dirs 23from ansible.errors import AnsibleError, AnsibleOptionsError 24from ansible.module_utils._text import to_native, to_text 25from ansible.module_utils.common._collections_compat import Container, Sequence 26from ansible.module_utils.common.json import AnsibleJSONEncoder 27from ansible.module_utils.six import string_types 28from ansible.parsing.plugin_docs import read_docstub 29from ansible.parsing.yaml.dumper import AnsibleDumper 30from ansible.plugins.loader import action_loader, fragment_loader 31from ansible.utils.collection_loader import AnsibleCollectionConfig 32from ansible.utils.collection_loader._collection_finder import _get_collection_name_from_path 33from ansible.utils.display import Display 34from ansible.utils.plugin_docs import ( 35 BLACKLIST, 36 remove_current_collection_from_versions_and_dates, 37 get_docstring, 38 get_versioned_doclink, 39) 40 41display = Display() 42 43 44def jdump(text): 45 try: 46 display.display(json.dumps(text, cls=AnsibleJSONEncoder, sort_keys=True, indent=4)) 47 except TypeError as e: 48 raise AnsibleError('We could not convert all the documentation into JSON as there was a conversion issue: %s' % to_native(e)) 49 50 51def add_collection_plugins(plugin_list, plugin_type, coll_filter=None): 52 53 # TODO: take into account runtime.yml once implemented 54 b_colldirs = list_collection_dirs(coll_filter=coll_filter) 55 for b_path in b_colldirs: 56 path = to_text(b_path, errors='surrogate_or_strict') 57 collname = _get_collection_name_from_path(b_path) 58 ptype = C.COLLECTION_PTYPE_COMPAT.get(plugin_type, plugin_type) 59 plugin_list.update(DocCLI.find_plugins(os.path.join(path, 'plugins', ptype), False, plugin_type, collection=collname)) 60 61 62class PluginNotFound(Exception): 63 pass 64 65 66class DocCLI(CLI): 67 ''' displays information on modules installed in Ansible libraries. 68 It displays a terse listing of plugins and their short descriptions, 69 provides a printout of their DOCUMENTATION strings, 70 and it can create a short "snippet" which can be pasted into a playbook. ''' 71 72 # default ignore list for detailed views 73 IGNORE = ('module', 'docuri', 'version_added', 'short_description', 'now_date', 'plainexamples', 'returndocs', 'collection') 74 JSON_IGNORE = ('attributes',) 75 76 # Warning: If you add more elements here, you also need to add it to the docsite build (in the 77 # ansible-community/antsibull repo) 78 _ITALIC = re.compile(r"\bI\(([^)]+)\)") 79 _BOLD = re.compile(r"\bB\(([^)]+)\)") 80 _MODULE = re.compile(r"\bM\(([^)]+)\)") 81 _LINK = re.compile(r"\bL\(([^)]+), *([^)]+)\)") 82 _URL = re.compile(r"\bU\(([^)]+)\)") 83 _REF = re.compile(r"\bR\(([^)]+), *([^)]+)\)") 84 _CONST = re.compile(r"\bC\(([^)]+)\)") 85 _RULER = re.compile(r"\bHORIZONTALLINE\b") 86 87 def __init__(self, args): 88 89 super(DocCLI, self).__init__(args) 90 self.plugin_list = set() 91 92 @classmethod 93 def tty_ify(cls, text): 94 95 t = cls._ITALIC.sub(r"`\1'", text) # I(word) => `word' 96 t = cls._BOLD.sub(r"*\1*", t) # B(word) => *word* 97 t = cls._MODULE.sub("[" + r"\1" + "]", t) # M(word) => [word] 98 t = cls._URL.sub(r"\1", t) # U(word) => word 99 t = cls._LINK.sub(r"\1 <\2>", t) # L(word, url) => word <url> 100 t = cls._REF.sub(r"\1", t) # R(word, sphinx-ref) => word 101 t = cls._CONST.sub("`" + r"\1" + "'", t) # C(word) => `word' 102 t = cls._RULER.sub("\n{0}\n".format("-" * 13), t) # HORIZONTALLINE => ------- 103 104 return t 105 106 def init_parser(self): 107 108 coll_filter = 'A supplied argument will be used for filtering, can be a namespace or full collection name.' 109 110 super(DocCLI, self).init_parser( 111 desc="plugin documentation tool", 112 epilog="See man pages for Ansible CLI options or website for tutorials https://docs.ansible.com" 113 ) 114 opt_help.add_module_options(self.parser) 115 opt_help.add_basedir_options(self.parser) 116 117 self.parser.add_argument('args', nargs='*', help='Plugin', metavar='plugin') 118 self.parser.add_argument("-t", "--type", action="store", default='module', dest='type', 119 help='Choose which plugin type (defaults to "module"). ' 120 'Available plugin types are : {0}'.format(C.DOCUMENTABLE_PLUGINS), 121 choices=C.DOCUMENTABLE_PLUGINS) 122 self.parser.add_argument("-j", "--json", action="store_true", default=False, dest='json_format', 123 help='Change output into json format.') 124 125 exclusive = self.parser.add_mutually_exclusive_group() 126 exclusive.add_argument("-F", "--list_files", action="store_true", default=False, dest="list_files", 127 help='Show plugin names and their source files without summaries (implies --list). %s' % coll_filter) 128 exclusive.add_argument("-l", "--list", action="store_true", default=False, dest='list_dir', 129 help='List available plugins. %s' % coll_filter) 130 exclusive.add_argument("-s", "--snippet", action="store_true", default=False, dest='show_snippet', 131 help='Show playbook snippet for specified plugin(s)') 132 exclusive.add_argument("--metadata-dump", action="store_true", default=False, dest='dump', 133 help='**For internal testing only** Dump json metadata for all plugins.') 134 135 def post_process_args(self, options): 136 options = super(DocCLI, self).post_process_args(options) 137 138 display.verbosity = options.verbosity 139 140 return options 141 142 def display_plugin_list(self, results): 143 144 # format for user 145 displace = max(len(x) for x in self.plugin_list) 146 linelimit = display.columns - displace - 5 147 text = [] 148 149 # format display per option 150 if context.CLIARGS['list_files']: 151 # list plugin file names 152 for plugin in results.keys(): 153 filename = results[plugin] 154 text.append("%-*s %-*.*s" % (displace, plugin, linelimit, len(filename), filename)) 155 else: 156 # list plugin names and short desc 157 deprecated = [] 158 for plugin in results.keys(): 159 desc = DocCLI.tty_ify(results[plugin]) 160 161 if len(desc) > linelimit: 162 desc = desc[:linelimit] + '...' 163 164 if plugin.startswith('_'): # Handle deprecated # TODO: add mark for deprecated collection plugins 165 deprecated.append("%-*s %-*.*s" % (displace, plugin[1:], linelimit, len(desc), desc)) 166 else: 167 text.append("%-*s %-*.*s" % (displace, plugin, linelimit, len(desc), desc)) 168 169 if len(deprecated) > 0: 170 text.append("\nDEPRECATED:") 171 text.extend(deprecated) 172 173 # display results 174 DocCLI.pager("\n".join(text)) 175 176 def run(self): 177 178 super(DocCLI, self).run() 179 180 plugin_type = context.CLIARGS['type'] 181 do_json = context.CLIARGS['json_format'] 182 183 if plugin_type in C.DOCUMENTABLE_PLUGINS: 184 loader = getattr(plugin_loader, '%s_loader' % plugin_type) 185 else: 186 raise AnsibleOptionsError("Unknown or undocumentable plugin type: %s" % plugin_type) 187 188 # add to plugin paths from command line 189 basedir = context.CLIARGS['basedir'] 190 if basedir: 191 AnsibleCollectionConfig.playbook_paths = basedir 192 loader.add_directory(basedir, with_subdir=True) 193 194 if context.CLIARGS['module_path']: 195 for path in context.CLIARGS['module_path']: 196 if path: 197 loader.add_directory(path) 198 199 # save only top level paths for errors 200 search_paths = DocCLI.print_paths(loader) 201 loader._paths = None # reset so we can use subdirs below 202 203 # list plugins names or filepath for type, both options share most code 204 if context.CLIARGS['list_files'] or context.CLIARGS['list_dir']: 205 206 coll_filter = None 207 if len(context.CLIARGS['args']) == 1: 208 coll_filter = context.CLIARGS['args'][0] 209 210 if coll_filter in ('', None): 211 paths = loader._get_paths_with_context() 212 for path_context in paths: 213 self.plugin_list.update( 214 DocCLI.find_plugins(path_context.path, path_context.internal, plugin_type)) 215 216 add_collection_plugins(self.plugin_list, plugin_type, coll_filter=coll_filter) 217 218 # get appropriate content depending on option 219 if context.CLIARGS['list_dir']: 220 results = self._get_plugin_list_descriptions(loader) 221 elif context.CLIARGS['list_files']: 222 results = self._get_plugin_list_filenames(loader) 223 224 if do_json: 225 jdump(results) 226 elif self.plugin_list: 227 self.display_plugin_list(results) 228 else: 229 display.warning("No plugins found.") 230 # dump plugin desc/data as JSON 231 elif context.CLIARGS['dump']: 232 plugin_data = {} 233 plugin_names = DocCLI.get_all_plugins_of_type(plugin_type) 234 for plugin_name in plugin_names: 235 plugin_info = DocCLI.get_plugin_metadata(plugin_type, plugin_name) 236 if plugin_info is not None: 237 plugin_data[plugin_name] = plugin_info 238 239 jdump(plugin_data) 240 else: 241 # display specific plugin docs 242 if len(context.CLIARGS['args']) == 0: 243 raise AnsibleOptionsError("Incorrect options passed") 244 245 # get the docs for plugins in the command line list 246 plugin_docs = {} 247 for plugin in context.CLIARGS['args']: 248 try: 249 doc, plainexamples, returndocs, metadata = DocCLI._get_plugin_doc(plugin, plugin_type, loader, search_paths) 250 except PluginNotFound: 251 display.warning("%s %s not found in:\n%s\n" % (plugin_type, plugin, search_paths)) 252 continue 253 except Exception as e: 254 display.vvv(traceback.format_exc()) 255 raise AnsibleError("%s %s missing documentation (or could not parse" 256 " documentation): %s\n" % 257 (plugin_type, plugin, to_native(e))) 258 259 if not doc: 260 # The doc section existed but was empty 261 continue 262 263 plugin_docs[plugin] = DocCLI._combine_plugin_doc(plugin, plugin_type, doc, plainexamples, returndocs, metadata) 264 265 if do_json: 266 for entry in plugin_docs.keys(): 267 for forbid in DocCLI.JSON_IGNORE: 268 try: 269 del plugin_docs[entry]['doc'][forbid] 270 except (KeyError, TypeError): 271 pass 272 jdump(plugin_docs) 273 else: 274 # Some changes to how plain text docs are formatted 275 text = [] 276 for plugin, doc_data in plugin_docs.items(): 277 textret = DocCLI.format_plugin_doc(plugin, plugin_type, 278 doc_data['doc'], doc_data['examples'], 279 doc_data['return'], doc_data['metadata']) 280 if textret: 281 text.append(textret) 282 else: 283 display.warning("No valid documentation was retrieved from '%s'" % plugin) 284 285 if text: 286 DocCLI.pager(''.join(text)) 287 return 0 288 289 @staticmethod 290 def get_all_plugins_of_type(plugin_type): 291 loader = getattr(plugin_loader, '%s_loader' % plugin_type) 292 plugin_list = set() 293 paths = loader._get_paths_with_context() 294 for path_context in paths: 295 plugins_to_add = DocCLI.find_plugins(path_context.path, path_context.internal, plugin_type) 296 plugin_list.update(plugins_to_add) 297 return sorted(set(plugin_list)) 298 299 @staticmethod 300 def get_plugin_metadata(plugin_type, plugin_name): 301 # if the plugin lives in a non-python file (eg, win_X.ps1), require the corresponding python file for docs 302 loader = getattr(plugin_loader, '%s_loader' % plugin_type) 303 result = loader.find_plugin_with_context(plugin_name, mod_type='.py', ignore_deprecated=True, check_aliases=True) 304 if not result.resolved: 305 raise AnsibleError("unable to load {0} plugin named {1} ".format(plugin_type, plugin_name)) 306 filename = result.plugin_resolved_path 307 collection_name = result.plugin_resolved_collection 308 309 try: 310 doc, __, __, __ = get_docstring(filename, fragment_loader, verbose=(context.CLIARGS['verbosity'] > 0), 311 collection_name=collection_name, is_module=(plugin_type == 'module')) 312 except Exception: 313 display.vvv(traceback.format_exc()) 314 raise AnsibleError("%s %s at %s has a documentation formatting error or is missing documentation." % (plugin_type, plugin_name, filename)) 315 316 if doc is None: 317 # Removed plugins don't have any documentation 318 return None 319 320 return dict( 321 name=plugin_name, 322 namespace=DocCLI.namespace_from_plugin_filepath(filename, plugin_name, loader.package_path), 323 description=doc.get('short_description', "UNKNOWN"), 324 version_added=doc.get('version_added', "UNKNOWN") 325 ) 326 327 @staticmethod 328 def namespace_from_plugin_filepath(filepath, plugin_name, basedir): 329 if not basedir.endswith('/'): 330 basedir += '/' 331 rel_path = filepath.replace(basedir, '') 332 extension_free = os.path.splitext(rel_path)[0] 333 namespace_only = extension_free.rsplit(plugin_name, 1)[0].strip('/_') 334 clean_ns = namespace_only.replace('/', '.') 335 if clean_ns == '': 336 clean_ns = None 337 338 return clean_ns 339 340 @staticmethod 341 def _get_plugin_doc(plugin, plugin_type, loader, search_paths): 342 # if the plugin lives in a non-python file (eg, win_X.ps1), require the corresponding python file for docs 343 result = loader.find_plugin_with_context(plugin, mod_type='.py', ignore_deprecated=True, check_aliases=True) 344 if not result.resolved: 345 raise PluginNotFound('%s was not found in %s' % (plugin, search_paths)) 346 plugin_name = result.plugin_resolved_name 347 filename = result.plugin_resolved_path 348 collection_name = result.plugin_resolved_collection 349 350 doc, plainexamples, returndocs, metadata = get_docstring( 351 filename, fragment_loader, verbose=(context.CLIARGS['verbosity'] > 0), 352 collection_name=collection_name, is_module=(plugin_type == 'module')) 353 354 # If the plugin existed but did not have a DOCUMENTATION element and was not removed, it's an error 355 if doc is None: 356 raise ValueError('%s did not contain a DOCUMENTATION attribute' % plugin) 357 358 doc['filename'] = filename 359 doc['collection'] = collection_name 360 return doc, plainexamples, returndocs, metadata 361 362 @staticmethod 363 def _combine_plugin_doc(plugin, plugin_type, doc, plainexamples, returndocs, metadata): 364 # generate extra data 365 if plugin_type == 'module': 366 # is there corresponding action plugin? 367 if plugin in action_loader: 368 doc['has_action'] = True 369 else: 370 doc['has_action'] = False 371 372 # return everything as one dictionary 373 return {'doc': doc, 'examples': plainexamples, 'return': returndocs, 'metadata': metadata} 374 375 @staticmethod 376 def format_plugin_doc(plugin, plugin_type, doc, plainexamples, returndocs, metadata): 377 collection_name = doc['collection'] 378 379 # TODO: do we really want this? 380 # add_collection_to_versions_and_dates(doc, '(unknown)', is_module=(plugin_type == 'module')) 381 # remove_current_collection_from_versions_and_dates(doc, collection_name, is_module=(plugin_type == 'module')) 382 # remove_current_collection_from_versions_and_dates( 383 # returndocs, collection_name, is_module=(plugin_type == 'module'), return_docs=True) 384 385 # assign from other sections 386 doc['plainexamples'] = plainexamples 387 doc['returndocs'] = returndocs 388 doc['metadata'] = metadata 389 390 if context.CLIARGS['show_snippet'] and plugin_type == 'module': 391 text = DocCLI.get_snippet_text(doc) 392 else: 393 try: 394 text = DocCLI.get_man_text(doc, collection_name, plugin_type) 395 except Exception as e: 396 raise AnsibleError("Unable to retrieve documentation from '%s' due to: %s" % (plugin, to_native(e))) 397 398 return text 399 400 @staticmethod 401 def find_plugins(path, internal, ptype, collection=None): 402 # if internal, collection could be set to `ansible.builtin` 403 404 display.vvvv("Searching %s for plugins" % path) 405 406 plugin_list = set() 407 408 if not os.path.exists(path): 409 display.vvvv("%s does not exist" % path) 410 return plugin_list 411 412 if not os.path.isdir(path): 413 display.vvvv("%s is not a directory" % path) 414 return plugin_list 415 416 bkey = ptype.upper() 417 for plugin in os.listdir(path): 418 display.vvvv("Found %s" % plugin) 419 full_path = '/'.join([path, plugin]) 420 421 if plugin.startswith('.'): 422 continue 423 elif os.path.isdir(full_path): 424 continue 425 elif any(plugin.endswith(x) for x in C.BLACKLIST_EXTS): 426 continue 427 elif plugin.startswith('__'): 428 continue 429 elif plugin in C.IGNORE_FILES: 430 continue 431 elif plugin .startswith('_'): 432 if os.path.islink(full_path): # avoids aliases 433 continue 434 435 plugin = os.path.splitext(plugin)[0] # removes the extension 436 plugin = plugin.lstrip('_') # remove underscore from deprecated plugins 437 438 if plugin not in BLACKLIST.get(bkey, ()): 439 440 if collection: 441 plugin = '%s.%s' % (collection, plugin) 442 443 plugin_list.add(plugin) 444 display.vvvv("Added %s" % plugin) 445 446 return plugin_list 447 448 def _get_plugin_list_descriptions(self, loader): 449 450 descs = {} 451 plugins = self._get_plugin_list_filenames(loader) 452 for plugin in plugins.keys(): 453 454 filename = plugins[plugin] 455 456 doc = None 457 try: 458 doc = read_docstub(filename) 459 except Exception: 460 display.warning("%s has a documentation formatting error" % plugin) 461 continue 462 463 if not doc or not isinstance(doc, dict): 464 desc = 'UNDOCUMENTED' 465 else: 466 desc = doc.get('short_description', 'INVALID SHORT DESCRIPTION').strip() 467 468 descs[plugin] = desc 469 470 return descs 471 472 def _get_plugin_list_filenames(self, loader): 473 pfiles = {} 474 for plugin in sorted(self.plugin_list): 475 476 try: 477 # if the module lives in a non-python file (eg, win_X.ps1), require the corresponding python file for docs 478 filename = loader.find_plugin(plugin, mod_type='.py', ignore_deprecated=True, check_aliases=True) 479 480 if filename is None: 481 continue 482 if filename.endswith(".ps1"): 483 continue 484 if os.path.isdir(filename): 485 continue 486 487 pfiles[plugin] = filename 488 489 except Exception as e: 490 raise AnsibleError("Failed reading docs at %s: %s" % (plugin, to_native(e)), orig_exc=e) 491 492 return pfiles 493 494 @staticmethod 495 def print_paths(finder): 496 ''' Returns a string suitable for printing of the search path ''' 497 498 # Uses a list to get the order right 499 ret = [] 500 for i in finder._get_paths(subdirs=False): 501 i = to_text(i, errors='surrogate_or_strict') 502 if i not in ret: 503 ret.append(i) 504 return os.pathsep.join(ret) 505 506 @staticmethod 507 def get_snippet_text(doc): 508 509 text = [] 510 desc = DocCLI.tty_ify(doc['short_description']) 511 text.append("- name: %s" % (desc)) 512 text.append(" %s:" % (doc['module'])) 513 pad = 31 514 subdent = " " * pad 515 limit = display.columns - pad 516 517 for o in sorted(doc['options'].keys()): 518 opt = doc['options'][o] 519 if isinstance(opt['description'], string_types): 520 desc = DocCLI.tty_ify(opt['description']) 521 else: 522 desc = DocCLI.tty_ify(" ".join(opt['description'])) 523 524 required = opt.get('required', False) 525 if not isinstance(required, bool): 526 raise("Incorrect value for 'Required', a boolean is needed.: %s" % required) 527 if required: 528 desc = "(required) %s" % desc 529 o = '%s:' % o 530 text.append(" %-20s # %s" % (o, textwrap.fill(desc, limit, subsequent_indent=subdent))) 531 text.append('') 532 533 return "\n".join(text) 534 535 @staticmethod 536 def _dump_yaml(struct, indent): 537 return DocCLI.tty_ify('\n'.join([indent + line for line in 538 yaml.dump(struct, default_flow_style=False, 539 Dumper=AnsibleDumper).split('\n')])) 540 541 @staticmethod 542 def add_fields(text, fields, limit, opt_indent, return_values=False, base_indent=''): 543 544 for o in sorted(fields): 545 # Create a copy so we don't modify the original (in case YAML anchors have been used) 546 opt = dict(fields[o]) 547 548 required = opt.pop('required', False) 549 if not isinstance(required, bool): 550 raise AnsibleError("Incorrect value for 'Required', a boolean is needed.: %s" % required) 551 if required: 552 opt_leadin = "=" 553 else: 554 opt_leadin = "-" 555 556 text.append("%s%s %s" % (base_indent, opt_leadin, o)) 557 558 if 'description' not in opt: 559 raise AnsibleError("All (sub-)options and return values must have a 'description' field") 560 if isinstance(opt['description'], list): 561 for entry_idx, entry in enumerate(opt['description'], 1): 562 if not isinstance(entry, string_types): 563 raise AnsibleError("Expected string in description of %s at index %s, got %s" % (o, entry_idx, type(entry))) 564 text.append(textwrap.fill(DocCLI.tty_ify(entry), limit, initial_indent=opt_indent, subsequent_indent=opt_indent)) 565 else: 566 if not isinstance(opt['description'], string_types): 567 raise AnsibleError("Expected string in description of %s, got %s" % (o, type(opt['description']))) 568 text.append(textwrap.fill(DocCLI.tty_ify(opt['description']), limit, initial_indent=opt_indent, subsequent_indent=opt_indent)) 569 del opt['description'] 570 571 aliases = '' 572 if 'aliases' in opt: 573 if len(opt['aliases']) > 0: 574 aliases = "(Aliases: " + ", ".join(to_text(i) for i in opt['aliases']) + ")" 575 del opt['aliases'] 576 choices = '' 577 if 'choices' in opt: 578 if len(opt['choices']) > 0: 579 choices = "(Choices: " + ", ".join(to_text(i) for i in opt['choices']) + ")" 580 del opt['choices'] 581 default = '' 582 if not return_values: 583 if 'default' in opt or not required: 584 default = "[Default: %s" % to_text(opt.pop('default', '(null)')) + "]" 585 586 text.append(textwrap.fill(DocCLI.tty_ify(aliases + choices + default), limit, 587 initial_indent=opt_indent, subsequent_indent=opt_indent)) 588 589 suboptions = [] 590 for subkey in ('options', 'suboptions', 'contains', 'spec'): 591 if subkey in opt: 592 suboptions.append((subkey, opt.pop(subkey))) 593 594 conf = {} 595 for config in ('env', 'ini', 'yaml', 'vars', 'keywords'): 596 if config in opt and opt[config]: 597 # Create a copy so we don't modify the original (in case YAML anchors have been used) 598 conf[config] = [dict(item) for item in opt.pop(config)] 599 for ignore in DocCLI.IGNORE: 600 for item in conf[config]: 601 if ignore in item: 602 del item[ignore] 603 604 if conf: 605 text.append(DocCLI._dump_yaml({'set_via': conf}, opt_indent)) 606 607 # Remove empty version_added_collection 608 if opt.get('version_added_collection') == '': 609 opt.pop('version_added_collection') 610 611 for k in sorted(opt): 612 if k.startswith('_'): 613 continue 614 if isinstance(opt[k], string_types): 615 text.append('%s%s: %s' % (opt_indent, k, 616 textwrap.fill(DocCLI.tty_ify(opt[k]), 617 limit - (len(k) + 2), 618 subsequent_indent=opt_indent))) 619 elif isinstance(opt[k], (Sequence)) and all(isinstance(x, string_types) for x in opt[k]): 620 text.append(DocCLI.tty_ify('%s%s: %s' % (opt_indent, k, ', '.join(opt[k])))) 621 else: 622 text.append(DocCLI._dump_yaml({k: opt[k]}, opt_indent)) 623 624 for subkey, subdata in suboptions: 625 text.append('') 626 text.append("%s%s:\n" % (opt_indent, subkey.upper())) 627 DocCLI.add_fields(text, subdata, limit, opt_indent + ' ', return_values, opt_indent) 628 if not suboptions: 629 text.append('') 630 631 @staticmethod 632 def get_man_text(doc, collection_name='', plugin_type=''): 633 # Create a copy so we don't modify the original 634 doc = dict(doc) 635 636 DocCLI.IGNORE = DocCLI.IGNORE + (context.CLIARGS['type'],) 637 opt_indent = " " 638 text = [] 639 pad = display.columns * 0.20 640 limit = max(display.columns - int(pad), 70) 641 642 plugin_name = doc.get(context.CLIARGS['type'], doc.get('name')) or doc.get('plugin_type') or plugin_type 643 if collection_name: 644 plugin_name = '%s.%s' % (collection_name, plugin_name) 645 646 text.append("> %s (%s)\n" % (plugin_name.upper(), doc.pop('filename'))) 647 648 if isinstance(doc['description'], list): 649 desc = " ".join(doc.pop('description')) 650 else: 651 desc = doc.pop('description') 652 653 text.append("%s\n" % textwrap.fill(DocCLI.tty_ify(desc), limit, initial_indent=opt_indent, 654 subsequent_indent=opt_indent)) 655 656 if doc.get('deprecated', False): 657 text.append("DEPRECATED: \n") 658 if isinstance(doc['deprecated'], dict): 659 if 'removed_at_date' in doc['deprecated']: 660 text.append( 661 "\tReason: %(why)s\n\tWill be removed in a release after %(removed_at_date)s\n\tAlternatives: %(alternative)s" % doc.pop('deprecated') 662 ) 663 else: 664 if 'version' in doc['deprecated'] and 'removed_in' not in doc['deprecated']: 665 doc['deprecated']['removed_in'] = doc['deprecated']['version'] 666 text.append("\tReason: %(why)s\n\tWill be removed in: Ansible %(removed_in)s\n\tAlternatives: %(alternative)s" % doc.pop('deprecated')) 667 else: 668 text.append("%s" % doc.pop('deprecated')) 669 text.append("\n") 670 671 if doc.pop('has_action', False): 672 text.append(" * note: %s\n" % "This module has a corresponding action plugin.") 673 674 if doc.get('options', False): 675 text.append("OPTIONS (= is mandatory):\n") 676 DocCLI.add_fields(text, doc.pop('options'), limit, opt_indent) 677 text.append('') 678 679 if doc.get('notes', False): 680 text.append("NOTES:") 681 for note in doc['notes']: 682 text.append(textwrap.fill(DocCLI.tty_ify(note), limit - 6, 683 initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent)) 684 text.append('') 685 text.append('') 686 del doc['notes'] 687 688 if doc.get('seealso', False): 689 text.append("SEE ALSO:") 690 for item in doc['seealso']: 691 if 'module' in item: 692 text.append(textwrap.fill(DocCLI.tty_ify('Module %s' % item['module']), 693 limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent)) 694 description = item.get('description', 'The official documentation on the %s module.' % item['module']) 695 text.append(textwrap.fill(DocCLI.tty_ify(description), limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' ')) 696 text.append(textwrap.fill(DocCLI.tty_ify(get_versioned_doclink('modules/%s_module.html' % item['module'])), 697 limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent)) 698 elif 'name' in item and 'link' in item and 'description' in item: 699 text.append(textwrap.fill(DocCLI.tty_ify(item['name']), 700 limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent)) 701 text.append(textwrap.fill(DocCLI.tty_ify(item['description']), 702 limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' ')) 703 text.append(textwrap.fill(DocCLI.tty_ify(item['link']), 704 limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' ')) 705 elif 'ref' in item and 'description' in item: 706 text.append(textwrap.fill(DocCLI.tty_ify('Ansible documentation [%s]' % item['ref']), 707 limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent)) 708 text.append(textwrap.fill(DocCLI.tty_ify(item['description']), 709 limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' ')) 710 text.append(textwrap.fill(DocCLI.tty_ify(get_versioned_doclink('/#stq=%s&stp=1' % item['ref'])), 711 limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' ')) 712 713 text.append('') 714 text.append('') 715 del doc['seealso'] 716 717 if doc.get('requirements', False): 718 req = ", ".join(doc.pop('requirements')) 719 text.append("REQUIREMENTS:%s\n" % textwrap.fill(DocCLI.tty_ify(req), limit - 16, initial_indent=" ", subsequent_indent=opt_indent)) 720 721 # Generic handler 722 for k in sorted(doc): 723 if k in DocCLI.IGNORE or not doc[k]: 724 continue 725 if isinstance(doc[k], string_types): 726 text.append('%s: %s' % (k.upper(), textwrap.fill(DocCLI.tty_ify(doc[k]), limit - (len(k) + 2), subsequent_indent=opt_indent))) 727 elif isinstance(doc[k], (list, tuple)): 728 text.append('%s: %s' % (k.upper(), ', '.join(doc[k]))) 729 else: 730 # use empty indent since this affects the start of the yaml doc, not it's keys 731 text.append(DocCLI._dump_yaml({k.upper(): doc[k]}, '')) 732 del doc[k] 733 text.append('') 734 735 if doc.get('plainexamples', False): 736 text.append("EXAMPLES:") 737 text.append('') 738 if isinstance(doc['plainexamples'], string_types): 739 text.append(doc.pop('plainexamples').strip()) 740 else: 741 text.append(yaml.dump(doc.pop('plainexamples'), indent=2, default_flow_style=False)) 742 text.append('') 743 text.append('') 744 745 if doc.get('returndocs', False): 746 text.append("RETURN VALUES:") 747 DocCLI.add_fields(text, doc.pop('returndocs'), limit, opt_indent, return_values=True) 748 749 return "\n".join(text) 750