diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2 index b829dd42a5..a2f6046445 100644 --- a/docs/templates/plugin.rst.j2 +++ b/docs/templates/plugin.rst.j2 @@ -144,6 +144,7 @@ Parameters {% elif choice is sameas false %} {% set choice = 'no' %} {% endif %} + {# Format default values differently (whenever a choice is one of the default values) #} {% if (value.default is not list and value.default == choice) or (value.default is list and choice in value.default) %}
  • @{ choice | escape }@ ←
  • {% else %} @@ -152,8 +153,12 @@ Parameters {% endfor %} {% endif %} - {# Show default value, when multiple choice or no choices #} - {% if value.default is defined and value.default not in value.choices %} + {# Show default value on a separate line when there is a non-None default (None + is usually a sentinel that shows the user didn't specify it) and there + either are no choices (like a freeform string) or the default does not exist + in choices + #} + {% if value.default is defined and value.default is not none and (not value.choices or value.default not in value.choices) %} Default:
    @{ value.default | tojson | escape }@
    {% endif %} diff --git a/hacking/build_library/build_ansible/command_plugins/plugin_formatter.py b/hacking/build_library/build_ansible/command_plugins/plugin_formatter.py index 784225e1b8..815daf3483 100644 --- a/hacking/build_library/build_ansible/command_plugins/plugin_formatter.py +++ b/hacking/build_library/build_ansible/command_plugins/plugin_formatter.py @@ -380,6 +380,19 @@ def process_options(module, options, full_key=None): if 'version_added' in v and too_old(v['version_added']): del v['version_added'] + # Set default values so that consumers can count on these being present Should really + # do this for all of the values that are optional but the template may rely on certain + # values being unset rather than falsey. antsibull sets default values and the + # templates were modified to check for falsey rather than existence so 2.10.x will do + # this the right way. + defaults = { + 'choices': (), + } + + for key, default in defaults.items(): + if key not in v: + v[key] = default + if 'suboptions' in v and v['suboptions']: if isinstance(v['suboptions'], dict): process_options(module, v['suboptions'], full_key=full_key_k)