{#
 # Template for Ansible roles that have meta/argument_spec.yml for use with ansible-doc-template-extractor.
 # This template produces an .rst file.
 # For the input variables that are set, run: ansible-doc-template-extractor --help-template.
 #}
{% macro para_generation(paras, level) %}
{# Macro that generates a list of paragraphs #}
{% if paras is string %}
{{ "  " * level }}{{ paras | to_rst }}

{% elif paras is iterable %}
{%   for para in paras %}
{{ "  " * level }}{{ para | to_rst }}

{%   endfor %}
{% else %}
{{ "  " * level }}{{ para | to_rst }}
{% endif %}
{% endmacro %}
{% macro option_generation(opts, level) %}
{# Macro that generates a list of options, recursively #}
{%   set sorted = false %}{# Flag to sort options by name #}
{%   for name, spec in (opts | dictsort if sorted else opts.items()) if not name.startswith('_') %}
{%     if spec.required | default(False) == True %}
{%       set required_txt = "Required." %}
{%     elif spec.default is defined %}
{%       set required_txt = "Optional, default: {}.".format(spec.default) %}
{%     else %}
{%       set required_txt = "Optional." %}
{%     endif %}
{%     if spec.type == 'list' %}
{%       set type_txt = "list of {}".format(spec.elements) %}
{%     else %}
{%       set type_txt = spec.type %}
{%     endif %}
{%     if spec.choices is defined %}
{%       set choices_txt = "Choices: {}.".format(spec.choices | join(', ')) %}
{%     else %}
{%       set choices_txt = "" %}
{%     endif %}
{{ "  " * level }}* **{{ name }}** ({{ type_txt }}):

{{ para_generation(spec.description, level + 1) }}
{{ "  " * level }}  {{ required_txt | to_rst }}
{%     if spec.choices is defined %}

{{ "  " * level }}  {{ choices_txt | to_rst }}
{%     endif %}
{%     if spec.options is defined %}
{{ option_generation(spec.options, level + 1) }}
{%     endif %}

{%   endfor %}
{% endmacro %}

..
    # This file has been generated by ansible-doc-template-extractor.
    # Do not modify this file manually, but modify its spec file source!

.. _{{ name }}_role:

{% for role_name, role_dict in spec_file_dict.argument_specs.items() %}
{%   if role_name == 'main' %}
{%     set title = "Role {} -- {}".format(name, role_dict.short_description) %}
{%   else %}
{%     set title = "Subrole {}.{} -- {}".format(name, role_name, role_dict.short_description) %}
{%   endif %}
{{ title }}
{{ '=' * title | length }}

Synopsis
--------

{% if role_dict.description is iterable and role_dict.description is not string %}
{%   for item in role_dict.description %}
{{ para_generation(item, 0) }}
{%   endfor %}
{% else %}
{{ para_generation(role_dict.description, 0) }}
{% endif %}
{%   if role_dict.version_added is defined %}

Version added
-------------

{{ role_dict.version_added }}
{%   endif %}
{%   set has_in_params = role_dict.options.in_params is defined and role_dict.options.in_params.type | default(None) == 'dict' %}
{%   set has_out_params = role_dict.options.out_params is defined and role_dict.options.out_params.type | default(None) == 'dict' %}
{%   if has_in_params or has_out_params %}
{%     if has_in_params %}

Input Parameters
----------------

{{ para_generation(role_dict.options.in_params.description, 0) }}
{{ option_generation(role_dict.options.in_params.options, 0) }}
{%     endif %}
{%     if has_out_params %}

Output Parameters
-----------------

{{ para_generation(role_dict.options.out_params.description, 0) }}
{{ option_generation(role_dict.options.out_params.options, 0) }}
{%     endif %}
{%   else %}

Parameters
----------

{{ option_generation(role_dict.options, 0) }}
{%   endif %}
{%   if role_dict.author is defined %}

Authors
-------

{%     if role_dict.author is iterable and role_dict.author is not string %}
{%       for author in role_dict.author %}
* {{ author }}
{%       endfor %}
{%     else %}
* {{ role_dict.author }}
{%     endif %}
{%   endif %}
{% endfor %}
