made doc more tolerant and recursive for spec

lib/ansible/cli/doc.py

@@ -29,9 +29,9 @@ from ansible import constants as C
 from ansible.cli import CLI
 from ansible.errors import AnsibleError, AnsibleOptionsError
 from ansible.module_utils.six import string_types
+from ansible.parsing.yaml.dumper import AnsibleDumper
 from ansible.plugins import module_loader, action_loader, lookup_loader, callback_loader, cache_loader, connection_loader, strategy_loader, PluginLoader
 from ansible.utils import plugin_docs
-
 try:
     from __main__ import display
 except ImportError:
@@ -292,7 +292,7 @@ class DocCLI(CLI):
         for o in sorted(fields):
             opt = fields[o]
 
-            required = opt.get('required', False)
+            required = opt.pop('required', False)
             if not isinstance(required, bool):
                 raise("Incorrect value for 'Required', a boolean is needed.: %s" % required)
             if required:
@@ -307,14 +307,32 @@ class DocCLI(CLI):
                     text.append(textwrap.fill(CLI.tty_ify(entry), limit, initial_indent=opt_indent, subsequent_indent=opt_indent))
             else:
                 text.append(textwrap.fill(CLI.tty_ify(opt['description']), limit, initial_indent=opt_indent, subsequent_indent=opt_indent))
+            del opt['description']
 
+            aliases= ''
+            if 'aliases' in opt:
+                choices = "(Aliases: " + ", ".join(str(i) for i in opt['aliases']) + ")"
+                del opt['aliases']
             choices = ''
             if 'choices' in opt:
                 choices = "(Choices: " + ", ".join(str(i) for i in opt['choices']) + ")"
+                del opt['choices']
             default = ''
             if 'default' in opt or not required:
-                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))
+                default = "[Default: " +  str(opt.pop('default', '(null)')) + "]"
+            text.append(textwrap.fill(CLI.tty_ify(aliases + choices + default), limit, initial_indent=opt_indent, subsequent_indent=opt_indent))
+
+            if 'options' in opt:
+                text.append(opt_indent + "options:\n")
+                self.add_fields(text, opt['options'], limit, opt_indent + opt_indent)
+                text.append('')
+                del opt['options']
+
+            if 'spec' in opt:
+                text.append(opt_indent + "spec:\n")
+                self.add_fields(text, opt['spec'], limit, opt_indent + opt_indent)
+                text.append('')
+                del opt['spec']
 
             for conf in ('config', 'env_vars', 'host_vars'):
                 if conf in opt:
@@ -328,9 +346,21 @@ class DocCLI(CLI):
                                 pre = "   "
                         else:
                             text.append(textwrap.fill(CLI.tty_ify("  - %s" % entry), limit, initial_indent=opt_indent, subsequent_indent=opt_indent))
+                    del opt[conf]
 
-    def get_man_text(self, doc):
+            # unspecified keys
+            for k in opt:
+                if k.startswith('_'):
+                    continue
+                if isinstance(opt[k], string_types):
+                    text.append(textwrap.fill(CLI.tty_ify("%s: %s" % (k, opt[k])), limit, initial_indent=opt_indent, subsequent_indent=opt_indent))
+                elif isinstance(opt[k], (list, dict)):
+                    text.append(textwrap.fill(CLI.tty_ify("%s: %s" % (k, yaml.dump(opt[k], Dumper=AnsibleDumper, default_flow_style=False))),
+                                              limit, initial_indent=opt_indent, subsequent_indent=opt_indent))
+                else:
+                    display.vv("Skipping %s key cuase we don't know how to handle eet" % k)
 
+    def get_man_text(self, doc):
         opt_indent="        "
         text = []
         text.append("> %s    (%s)\n" % (doc[self.options.type].upper(), doc['filename']))