diff options
| -rw-r--r-- | docsite/rst/developing_modules.rst | 4 | ||||
| -rwxr-xr-x | hacking/module_formatter.py | 6 | ||||
| -rw-r--r-- | lib/ansible/cli/doc.py | 8 |
3 files changed, 9 insertions, 9 deletions
diff --git a/docsite/rst/developing_modules.rst b/docsite/rst/developing_modules.rst index 1ec1b4ecdd..2a5796dcd6 100644 --- a/docsite/rst/developing_modules.rst +++ b/docsite/rst/developing_modules.rst @@ -638,8 +638,8 @@ The following checklist items are important guidelines for people who want to c * Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience--readable both by experts and non-experts. This documentation is not meant to teach a total novice, but it also should not be reserved for the Illuminati (hard balance). * If an argument takes both C(True)/C(False) and C(Yes)/C(No), the documentation should use C(True) and C(False). * Descriptions should always start with a Capital letter and end with a full stop. Consistency always helps. - * The `required` setting should always be present, be it true *or* false - * If `required` is false, you should document `default`, even if the default is 'null' (which is the default if no parameter is supplied). Make sure default parameter in docs matches default parameter in code. + * The `required` setting is only required when true, otherwise it is assumed to be false. + * If `required` is false/missing, `default` may be specified (assumed 'null' if missing). Ensure that the default parameter in docs matches default parameter in code. * Documenting `default` is not needed for `required: true`. * Remove unnecessary doc like `aliases: []` or `choices: []`. * The version is not a float number and value the current development version. diff --git a/hacking/module_formatter.py b/hacking/module_formatter.py index 72245e533e..7a4005c044 100755 --- a/hacking/module_formatter.py +++ b/hacking/module_formatter.py @@ -289,8 +289,10 @@ def process_module(module, options, env, template, outputname, module_map, alias del doc['options'][k]['version_added'] if not 'description' in doc['options'][k]: raise AnsibleError("Missing required description for option %s in %s " % (k, module)) - if not 'required' in doc['options'][k]: - raise AnsibleError("Missing required 'required' for option %s in %s " % (k, module)) + + required_value = doc['options'][k].get('required', False) + if not isinstance(required_value, bool): + raise AnsibleError("Invalid required value '%s' for option '%s' in '%s' (must be truthy)" % (required_value, k, module)) if not isinstance(doc['options'][k]['description'],list): doc['options'][k]['description'] = [doc['options'][k]['description']] diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py index 27c3eea9d3..5a699f8a97 100644 --- a/lib/ansible/cli/doc.py +++ b/lib/ansible/cli/doc.py @@ -219,9 +219,7 @@ class DocCLI(CLI): opt = doc['options'][o] desc = CLI.tty_ify(" ".join(opt['description'])) - required = opt.get('required') - if required is None: - raise("Missing required field 'Required'") + required = opt.get('required', False) if not isinstance(required, bool): raise("Incorrect value for 'Required', a boolean is needed.: %s" % required) if required: @@ -275,8 +273,8 @@ class DocCLI(CLI): if 'choices' in opt: choices = ", ".join(str(i) for i in opt['choices']) desc = desc + " (Choices: " + choices + ")" - if 'default' in opt: - default = str(opt['default']) + if 'default' in opt or not required: + default = str(opt.get('default', '(null)')) desc = desc + " [Default: " + default + "]" text.append("%s\n" % textwrap.fill(CLI.tty_ify(desc), limit, initial_indent=opt_indent, subsequent_indent=opt_indent)) |