diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py index d5150be4ba..a160555cdd 100644 --- a/scripts/generators/asciidoc_fields.py +++ b/scripts/generators/asciidoc_fields.py @@ -43,10 +43,10 @@ def page_field_details(intermediate_nested): def render_fieldset(fieldset, intermediate_nested): - text = field_details_table_header().format( - fieldset_title=fieldset['title'], - fieldset_name=fieldset['name'], - fieldset_description=render_asciidoc_paragraphs(fieldset['description']) + text = field_details_table_header( + title=fieldset['title'], + name=fieldset['name'], + description=fieldset['description'] ) text += render_fields(fieldset['fields']) @@ -78,10 +78,11 @@ def render_field_allowed_values(field): if not 'allowed_values' in field: return '' allowed_values = ', '.join(ecs_helpers.list_extract_keys(field['allowed_values'], 'name')) - return field_acceptable_value_names().format( + + return field_acceptable_value_names( allowed_values=allowed_values, - field_flat_name=field['flat_name'], - field_dashed_name=field['dashed_name'], + flat_name=field['flat_name'], + dashed_name=field['dashed_name'] ) @@ -102,14 +103,15 @@ def render_field_details_row(field): if 'array' in field['normalize']: field_normalization = "\nNote: this field should contain an array of values.\n\n" - text = field_details_row().format( - field_flat_name=field['flat_name'], - field_description=render_asciidoc_paragraphs(field['description']), - field_example=example, - field_normalization=field_normalization, - field_level=field['level'], + text = field_details_row( + flat_name=field['flat_name'], + description=field['description'], field_type=field_type_with_mf, + example=example, + normalization=field_normalization, + level=field['level'] ) + return text @@ -118,13 +120,14 @@ def render_fieldset_reuse_section(fieldset, intermediate_nested): if not ('nestings' in fieldset or 'reusable' in fieldset): return '' - text = field_reuse_section().format( + text = field_reuse_section( reuse_of_fieldset=render_fieldset_reuses_text(fieldset) ) + if 'nestings' in fieldset: - text += nestings_table_header().format( - fieldset_name=fieldset['name'], - fieldset_title=fieldset['title'] + text += nestings_table_header( + name=fieldset['name'], + title=fieldset['title'] ) rows = [] for nested_fs_name in fieldset['nestings']: @@ -134,8 +137,14 @@ def render_fieldset_reuse_section(fieldset, intermediate_nested): 'name': nested_fs_name.split('.')[-1], 'short': ecs['short'] }) + for row in sorted(rows, key=lambda x: x['flat_nesting']): - text += render_nesting_row(row) + text += nestings_row( + nesting_name=row['name'], + flat_nesting=row['flat_nesting'], + nesting_short=row['short'] + ) + text += table_footer() return text @@ -160,18 +169,8 @@ def render_fieldset_reuses_text(fieldset): return text -def render_nesting_row(nesting): - text = nestings_row().format( - nesting_name=nesting['name'], - flat_nesting=nesting['flat_nesting'], - nesting_short=nesting['short'], - ) - return text - - # Templates - def table_footer(): return ''' |===== @@ -188,92 +187,57 @@ def generate_field_index(ecs_version, fieldsets, template_name='fields_template. # Main Fields Table - -def field_details_table_header(): - return ''' -[[ecs-{fieldset_name}]] -=== {fieldset_title} Fields - -{fieldset_description} - -==== {fieldset_title} Field Details - -[options="header"] -|===== -| Field | Description | Level - -// =============================================================== -''' - - -def field_details_row(): - return ''' -| {field_flat_name} -| {field_description} - -type: {field_type} - -{field_normalization} - -{field_example} - -| {field_level} - -// =============================================================== -''' +def field_details_table_header(title, name, description, template_name='field_details/table_header.j2'): + template = template_env.get_template(template_name) + return template.render(name=name, title=title, description=description) -def field_acceptable_value_names(): - return ''' -*Important*: The field value must be one of the following: +def field_details_row(flat_name, description, field_type, normalization, example, level, template_name='field_details/row.j2'): + template = template_env.get_template(template_name) + return template.render( + flat_name=flat_name, + description=description, + field_type=field_type, + normalization=normalization, + example=example, + level=level + ) -{allowed_values} -To learn more about when to use which value, visit the page -<> -''' +def field_acceptable_value_names(allowed_values, dashed_name, flat_name, template_name='field_details/acceptable_value_names.j2'): + template = template_env.get_template(template_name) + return template.render( + allowed_values=allowed_values, + dashed_name=dashed_name, + flat_name=flat_name + ) # Field reuse -def field_reuse_section(): - return ''' -==== Field Reuse - -{reuse_of_fieldset} - -''' +def field_reuse_section(reuse_of_fieldset, template_name='field_details/field_reuse_section.j2'): + template = template_env.get_template(template_name) + return template.render(reuse_of_fieldset=reuse_of_fieldset) # Nestings table -def nestings_table_header(): - return ''' -[[ecs-{fieldset_name}-nestings]] -===== Field sets that can be nested under {fieldset_title} - -[options="header"] -|===== -| Nested fields | Description - -// =============================================================== - -''' - - -def nestings_row(): - return ''' -| <> -| {nesting_short} +def nestings_table_header(name, title, template_name='field_details/nestings_table_header.j2'): + template = template_env.get_template(template_name) + return template.render(name=name, title=title) -// =============================================================== -''' +def nestings_row(nesting_name, flat_nesting, nesting_short, template_name='field_details/nestings_row.j2'): + template = template_env.get_template(template_name) + return template.render( + nesting_name=nesting_name, + flat_nesting=flat_nesting, + nesting_short=nesting_short + ) # Allowed values section - def page_field_values(intermediate_nested, template_name='field_values_template.j2'): category_fields = ['event.kind', 'event.category', 'event.type', 'event.outcome'] nested_fields = [] diff --git a/scripts/generators/templates/field_details/acceptable_value_names.j2 b/scripts/generators/templates/field_details/acceptable_value_names.j2 new file mode 100644 index 0000000000..6080445742 --- /dev/null +++ b/scripts/generators/templates/field_details/acceptable_value_names.j2 @@ -0,0 +1,8 @@ + +*Important*: The field value must be one of the following: + +{{ allowed_values }} + +To learn more about when to use which value, visit the page +<> + diff --git a/scripts/generators/templates/field_details/field_reuse_section.j2 b/scripts/generators/templates/field_details/field_reuse_section.j2 new file mode 100644 index 0000000000..37aa7ded45 --- /dev/null +++ b/scripts/generators/templates/field_details/field_reuse_section.j2 @@ -0,0 +1,6 @@ + +==== Field Reuse + +{{ reuse_of_fieldset }} + + diff --git a/scripts/generators/templates/field_details/nestings_row.j2 b/scripts/generators/templates/field_details/nestings_row.j2 new file mode 100644 index 0000000000..826af848bb --- /dev/null +++ b/scripts/generators/templates/field_details/nestings_row.j2 @@ -0,0 +1,7 @@ + +| <> +| {{ nesting_short }} + +// =============================================================== + + diff --git a/scripts/generators/templates/field_details/nestings_table_header.j2 b/scripts/generators/templates/field_details/nestings_table_header.j2 new file mode 100644 index 0000000000..2ef25791d9 --- /dev/null +++ b/scripts/generators/templates/field_details/nestings_table_header.j2 @@ -0,0 +1,11 @@ + +[[ecs-{{ name }}-nestings]] +===== Field sets that can be nested under {{ title }} + +[options="header"] +|===== +| Nested fields | Description + +// =============================================================== + + diff --git a/scripts/generators/templates/field_details/row.j2 b/scripts/generators/templates/field_details/row.j2 new file mode 100644 index 0000000000..90e2c8877f --- /dev/null +++ b/scripts/generators/templates/field_details/row.j2 @@ -0,0 +1,14 @@ + +| {{ flat_name }} +| {{ description|replace("\n", "\n\n") }} + +type: {{ field_type }} + +{{ normalization }} + +{{ example }} + +| {{ level }} + +// =============================================================== + diff --git a/scripts/generators/templates/field_details/table_header.j2 b/scripts/generators/templates/field_details/table_header.j2 new file mode 100644 index 0000000000..4496e8e768 --- /dev/null +++ b/scripts/generators/templates/field_details/table_header.j2 @@ -0,0 +1,14 @@ + +[[ecs-{{ name }}]] +=== {{ title }} Fields + +{{ description|replace("\n", "\n\n") }} + +==== {{ title }} Field Details + +[options="header"] +|===== +| Field | Description | Level + +// =============================================================== +