Item templates

[ociu]

Instead of the annoying admonition node formatting, provide a template mechanism so user can decide how to format items, in a similar way to how matplotlib plot directive does.

In order to allow different templates in the same project, regexps and/or class options could be used to decide which items a template should be applied to.

Example template: defining items as term-definition pairs, with highlighted caption as first definition line:

"""
{{ item_id }}
    **{{ item_caption }}**
    {{ item_body }}
"""

[ociu]

Finally the example/default template had to be slightly different, in order to be correctly rendered:

{{ id }}
{%- if caption %}
    **{{ caption }}**
{% endif %}
    {{ content|indent(4) }}

Multi-line strings have to be explicitly indented, and caption treated as optional with if statements. Input data (id, caption, content...) is exactly the same used internally to store item information.

A lot has to be written on this topic... Templating is definitely not easy, extreme care has to be taken and Jinja2 templating well understood. Will try to explain it further in the README file and make some impressing examples (as the results can be absolutely amazing :)). As a summary, Instead of giving the traceabiity extension more power to handle templates, I decided to keep it as simple as possible, and give the user full freedom in the template, giving as input all the item information. A user can do magic just within one template.