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)