cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Make 'required' optional in module docs (#15906)

Browse source 
Updated module dev docs, doc build, ansible-doc to match
This commit is contained in:
Matt Davis 2016-05-18 16:57:36 -07:00 committed by Toshio Kuratomi
parent 71a707fba5
commit ec2cb07988
3 changed files with 9 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docsite/rst/developing_modules.rst
View file

@ -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). * 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). * 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. * 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 * The `required` setting is only required when true, otherwise it is assumed to be 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. * 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`. * Documenting `default` is not needed for `required: true`.
* Remove unnecessary doc like `aliases: []` or `choices: []`. * Remove unnecessary doc like `aliases: []` or `choices: []`.
* The version is not a float number and value the current development version. * The version is not a float number and value the current development version.

6
hacking/module_formatter.py
View file

@ -289,8 +289,10 @@ def process_module(module, options, env, template, outputname, module_map, alias
del doc['options'][k]['version_added'] del doc['options'][k]['version_added']
if not 'description' in doc['options'][k]: if not 'description' in doc['options'][k]:
raise AnsibleError("Missing required description for option %s in %s " % (k, module)) 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): if not isinstance(doc['options'][k]['description'],list):
doc['options'][k]['description'] = [doc['options'][k]['description']] doc['options'][k]['description'] = [doc['options'][k]['description']]

8
lib/ansible/cli/doc.py
View file

@ -219,9 +219,7 @@ class DocCLI(CLI):
opt = doc['options'][o] opt = doc['options'][o]
desc = CLI.tty_ify(" ".join(opt['description'])) desc = CLI.tty_ify(" ".join(opt['description']))
required = opt.get('required') required = opt.get('required', False)
if required is None:
raise("Missing required field 'Required'")
if not isinstance(required, bool): if not isinstance(required, bool):
raise("Incorrect value for 'Required', a boolean is needed.: %s" % required) raise("Incorrect value for 'Required', a boolean is needed.: %s" % required)
if required: if required:
@ -275,8 +273,8 @@ class DocCLI(CLI):
if 'choices' in opt: if 'choices' in opt:
choices = ", ".join(str(i) for i in opt['choices']) choices = ", ".join(str(i) for i in opt['choices'])
desc = desc + " (Choices: " + choices + ")" desc = desc + " (Choices: " + choices + ")"
if 'default' in opt: if 'default' in opt or not required:
default = str(opt['default']) default = str(opt.get('default', '(null)'))
desc = desc + " [Default: " + default + "]" desc = desc + " [Default: " + default + "]"
text.append("%s\n" % textwrap.fill(CLI.tty_ify(desc), limit, initial_indent=opt_indent, subsequent_indent=opt_indent)) text.append("%s\n" % textwrap.fill(CLI.tty_ify(desc), limit, initial_indent=opt_indent, subsequent_indent=opt_indent))