Refactor asciidocs to use jinja2 templates

[ebeahan]

This PR refactors the ascii_fields generator to use jinja2 templating. Motivation is better decoupling the asciidoc formatting from the content generation.

Template changes can be made in the ./scripts/generators/templates directory without modifying the generator code directly. Formatting was tested by generating docs and ensuring no changes from their existing structure and content.

Templating implementation

The @templated('template_file_name') decorator is used to inject the additional functionality that renders and returns the template's content to the generator.

@templated('fields_template.j2')
def page_field_index(intermediate_nested, ecs_version):
    fieldsets = ecs_helpers.dict_sorted_by_keys(intermediate_nested, ['group', 'name'])
    return dict(ecs_version=ecs_version, fieldsets=fieldsets)

Decorated functions should return a dict used to generate the template. When the decorated function returns, the dictionary is passed to the template renderer.

NOTE: Leaving as draft until #864 is merged. I'll update and resolve conflicts accordingly. #864 is merged 😎

[webmat]

This looks great! Thanks Eric :-)

The main goal of adding these templates is to make contributions to ECS simpler for non technical or non-Python contributors. This is a great step in this direction!

In the same vein, I have a few more small things I think we could do here:

• Can we move the templates to scripts/templates/...? They'll be a bit easier to find for folks who never play in the code.
• Can we add to the "Documentation" section of CONTRIBUTING.md, with some details about this?
  • mention which files are generated, and where to find their templates
  • we have a link to asciidoc already, we can add another one for Jinja2
  • [stretch goal] add a mini primer to help people know what's J2 vs what's asciidoc. Perhaps we only need to cover {{ }} and {% %}?

[ebeahan]

@webmat thanks for the feedback! Let me know your thoughts on the additions to CONTRIBUTING.md.

[webmat]

Looking great! Thanks for the adjustments :-)