/hacking/templates/rst.j2

  1.. _@{ module }@:
  2
  3{% if short_description %}
  4{% set title = module + ' - ' + short_description|convert_symbols_to_format %}
  5{% else %}
  6{% set title = module %}
  7{% endif %}
  8{% set title_len = title|length %}
  9
 10@{ title }@
 11@{ '+' * title_len }@
 12
 13{% if author %}
 14:Author: @{ author }@
 15{% endif %}
 16
 17.. contents::
 18   :local:
 19   :depth: 1
 20
 21{# ------------------------------------------
 22 #
 23 # Please note: this looks like a core dump
 24 # but it isn't one.
 25 #
 26 --------------------------------------------#}
 27
 28Synopsis
 29--------
 30
 31{% if version_added is defined -%}
 32.. versionadded:: @{ version_added }@
 33{% endif %}
 34
 35{% for desc in description -%}
 36@{ desc | convert_symbols_to_format }@
 37{% endfor %}
 38
 39{% if options -%}
 40Options
 41-------
 42
 43.. raw:: html
 44
 45    <table border=1 cellpadding=4>
 46    <tr>
 47    <th class="head">parameter</th>
 48    <th class="head">required</th>
 49    <th class="head">default</th>
 50    <th class="head">choices</th>
 51    <th class="head">comments</th>
 52    </tr>
 53    {% for k in option_keys %}
 54    {% set v = options[k] %}
 55    <tr>
 56    <td>@{ k }@</td>
 57    <td>{% if v.get('required', False) %}yes{% else %}no{% endif %}</td>
 58    <td>{% if v['default'] %}@{ v['default'] }@{% endif %}</td>
 59    {% if v.get('type', 'not_bool') == 'bool' %}
 60    <td><ul><li>yes</li><li>no</li></ul></td>
 61    {% else %}
 62    <td><ul>{% for choice in v.get('choices',[]) -%}<li>@{ choice }@</li>{% endfor -%}</ul></td>
 63    {% endif %}
 64    <td>{% for desc in v.description -%}@{ desc | html_ify }@{% endfor -%}{% if v['version_added'] %} (added in Ansible @{v['version_added']}@){% endif %}</td>
 65    </tr>
 66    {% endfor %}
 67    </table>
 68{% endif %}
 69
 70{% if requirements %}
 71{% for req in requirements %}
 72
 73.. note:: Requires @{ req | convert_symbols_to_format }@
 74
 75{% endfor %}
 76{% endif %}
 77
 78{% if examples or plainexamples %}
 79Examples
 80--------
 81
 82.. raw:: html
 83
 84{% for example in examples %}
 85    {% if example['description'] %}<p>@{ example['description'] | html_ify }@</p>{% endif %}
 86    <p>
 87    <pre>
 88@{ example['code'] | escape | indent(4, True) }@
 89    </pre>
 90    </p>
 91{% endfor %}
 92    <br/>
 93
 94{% if plainexamples %}
 95
 96::
 97
 98@{ plainexamples | indent(4, True) }@
 99{% endif %}
100{% endif %}
101
102{% if notes %}
103{% for note in notes %}
104.. note:: @{ note | convert_symbols_to_format }@
105{% endfor %}
106{% endif %}
107