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

Consolidate field-details doc template #897

Merged
merged 8 commits into from
Aug 20, 2020
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
refactoring to simplify field-details template logic
remove one level of iteration

improve var name

remove render_fieldset_reuse_text filter from template

remove render_nestings_reuse_section filter

remove sorting from j2 on fieldset fields list

refactor logic for extracting allowed_values names

linting
ebeahan committed Aug 10, 2020
commit 2f026af19dde358e5a4d7b142cd4fd90ba116d31
1 change: 0 additions & 1 deletion docs/field-details.asciidoc
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@

[[ecs-base]]
=== Base Fields

65 changes: 55 additions & 10 deletions scripts/generators/asciidoc_fields.py
Original file line number Diff line number Diff line change
@@ -14,16 +14,26 @@ def generate(nested, ecs_version, out_dir):
# Helpers


def render_fieldset_reuse_text(fields):
"""Renders the expected nesting locations.
def render_fieldset_reuse_text(fieldset):
"""Renders the expected nesting locations
if the the `reusable` object is present.

:param fields: The reusable, expected fields
:param fieldset: The fieldset to evaluate
"""
sorted_fields = sorted(fields, key=lambda k: k['full'])
if not fieldset.get('reusable'):
return None
reusable_fields = fieldset['reusable']['expected']
sorted_fields = sorted(reusable_fields, key=lambda k: k['full'])
return map(lambda f: f['full'], sorted_fields)


def render_nestings_reuse_section(fieldset):
"""Renders the reuse section entries.

:param fieldset: The target fieldset
"""
if not fieldset.get('reused_here'):
return None
rows = []
for reused_here_entry in fieldset['reused_here']:
rows.append({
@@ -35,6 +45,33 @@ def render_nestings_reuse_section(fieldset):
return sorted(rows, key=lambda x: x['flat_nesting'])


def extract_allowed_values_key_names(field):
"""Extracts the `name` keys from the field's
allowed_values if present in the field
object.

:param field: The target field
"""
if not field.get('allowed_values'):
return []
return ecs_helpers.list_extract_keys(field['allowed_values'], 'name')


def sort_fields(fieldset):
"""Prepares a fieldset's fields for being
passed into the j2 template for rendering. This
includes sorting them into a list of objects and
adding a field for the names of any allowed values
for the field, if present.

:param fieldset: The target fieldset
"""
fields_list = list(fieldset['fields'].values())
for field in fields_list:
field['allowed_value_names'] = extract_allowed_values_key_names(field)
return sorted(fields_list, key=lambda field: field['name'])


def templated(template_name):
"""Decorator function to simplify rendering a template.

@@ -75,10 +112,6 @@ def save_asciidoc(f, text):
TEMPLATE_DIR = path.join(path.dirname(path.abspath(__file__)), '../templates')
template_loader = jinja2.FileSystemLoader(searchpath=TEMPLATE_DIR)
template_env = jinja2.Environment(loader=template_loader)
template_env.filters.update({
'list_extract_keys': ecs_helpers.list_extract_keys,
'render_fieldset_reuse_text': render_fieldset_reuse_text,
'render_nestings_reuse_section': render_nestings_reuse_section})

# Rendering schemas

@@ -93,10 +126,22 @@ def page_field_index(nested, ecs_version):

# Field Details Page

@templated('field_details.j2')
def page_field_details(nested):
fieldsets = ecs_helpers.dict_sorted_by_keys(nested, ['group', 'name'])
return dict(fieldsets=fieldsets)
results = (generate_field_details_page(fieldset) for fieldset in fieldsets)
return ''.join(results)


@templated('field_details.j2')
def generate_field_details_page(fieldset):
# render field reuse text section
sorted_reuse_fields = render_fieldset_reuse_text(fieldset)
render_nestings_reuse_fields = render_nestings_reuse_section(fieldset)
sorted_fields = sort_fields(fieldset)
return dict(fieldset=fieldset,
sorted_reuse_fields=sorted_reuse_fields,
render_nestings_reuse_section=render_nestings_reuse_fields,
sorted_fields=sorted_fields)


# Allowed values section
13 changes: 3 additions & 10 deletions scripts/templates/field_details.j2
Original file line number Diff line number Diff line change
@@ -1,6 +1,3 @@

{% for fieldset in fieldsets -%}

{# Title & Description -#}
[[ecs-{{ fieldset['name'] }}]]
=== {{ fieldset['title'] }} Fields
@@ -17,7 +14,7 @@
// ===============================================================

{# Iterate through each field in the set -#}
{% for _, field in fieldset['fields'].items()|sort -%}
{% for field in sorted_fields -%}
{% if 'original_fieldset' not in field -%}

{# `Field` column -#}
@@ -45,11 +42,9 @@ Note: this field should contain an array of values.

{% endif %}
ebeahan marked this conversation as resolved.
Show resolved Hide resolved
{% if 'allowed_values' in field %}
{% set allowed_values = field['allowed_values']|list_extract_keys('name')|join(', ') -%}

*Important*: The field value must be one of the following:

{{ allowed_values }}
{{ field['allowed_value_names']|join(', ') }}

To learn more about when to use which value, visit the page
<<ecs-allowed-values-{{ field['dashed_name'] }},allowed values for {{ field['flat_name'] }}>>
@@ -75,7 +70,6 @@ example: `{{ field['example'] }}`
==== Field Reuse

{% if 'reusable' in fieldset -%}
{% set sorted_reuse_fields = fieldset['reusable']['expected']|render_fieldset_reuse_text -%}

The `{{ fieldset['name'] }}` fields are expected to be nested at: `{{ sorted_reuse_fields|join("`, `") }}`.

@@ -103,7 +97,7 @@ Note also that the `{{ fieldset['name'] }}` fields are not expected to be used d
// ===============================================================


{% for entry in fieldset|render_nestings_reuse_section -%}
{% for entry in render_nestings_reuse_section -%}

| <<ecs-{{ entry['name'] }},{{ entry['flat_nesting'] }}>>
| {{ entry['short'] }}
@@ -117,4 +111,3 @@ Note also that the `{{ fieldset['name'] }}` fields are not expected to be used d

{% endif %}
{%- endif %}
{%- endfor %}