Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor asciidocs to use jinja2 templates #865

Merged
merged 18 commits into from
Jun 25, 2020

Conversation

ebeahan
Copy link
Member

@ebeahan ebeahan commented Jun 4, 2020

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 😎

@ebeahan ebeahan self-assigned this Jun 4, 2020
@ebeahan ebeahan marked this pull request as ready for review June 12, 2020 19:13
@ebeahan ebeahan requested a review from webmat June 12, 2020 19:13
Copy link
Contributor

@webmat webmat left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 {% %}?

CHANGELOG.next.md Outdated Show resolved Hide resolved
scripts/generators/asciidoc_fields.py Outdated Show resolved Hide resolved
scripts/generators/asciidoc_fields.py Show resolved Hide resolved
scripts/generators/asciidoc_fields.py Show resolved Hide resolved
scripts/generators/templates/field_details/row.j2 Outdated Show resolved Hide resolved
@ebeahan
Copy link
Member Author

ebeahan commented Jun 24, 2020

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

Copy link
Contributor

@webmat webmat left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking great! Thanks for the adjustments :-)

@ebeahan ebeahan merged commit 75da22b into elastic:master Jun 25, 2020
@ebeahan ebeahan deleted the refactor-jinja2 branch June 25, 2020 20:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants