From 14a8d524eb951b8b1e23bd1b74d6a66cbbd3b8ba Mon Sep 17 00:00:00 2001 From: Eric Beahan Date: Tue, 13 Jul 2021 16:25:34 -0500 Subject: [PATCH] Present `beta` tooltip for categorization values (#1511) * include beta tooltip if beta attribute is present * test for presence of beta fields * changelog * add note about beta support in the README --- CHANGELOG.next.md | 1 + schemas/README.md | 9 ++-- scripts/templates/field_values.j2 | 8 ++- scripts/tests/test_asciidoc_fields.py | 75 +++++++++++++++++++++++++++ 4 files changed, 88 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md index f4a98d88ef..4fe36ce489 100644 --- a/CHANGELOG.next.md +++ b/CHANGELOG.next.md @@ -65,6 +65,7 @@ Thanks, you're awesome :-) --> * Support `match_only_text` data type in Go code generator. #1418 * Support for multi-level, self-nestings. #1459 +* `beta` attribute now supported on categorization allowed values. #1511 #### Improvements diff --git a/schemas/README.md b/schemas/README.md index d36a2942f2..19e8a8b1a9 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -32,7 +32,7 @@ Optional field set attributes: - type (ignored): at this level, should always be `group` - reusable (optional): Used to identify which field sets are expected to be reused in multiple places. See "Field set reuse" for details. -- short_override: Used to override the top-level fieldset's short description when nesting. +- short_override: Used to override the top-level fieldset's short description when nesting. See "Field set reuse" for details. - beta: Adds a beta marker for the entire fieldset. The text provided in this attribute is used as content of the beta marker in the documentation. Beta notices should not have newlines. @@ -59,7 +59,7 @@ The `reusable` attribute is composed of `top_level`, `expected`, and `short_over events or is it only expected in the nested locations? - expected (default []): list of places the field set's fields are expected. There are two valid notations to list expected locations. -- short_override (optional, default null): Sets the short description for the +- short_override (optional, default null): Sets the short description for the nested field, overriding the default top-level short description. The "flat" (or dotted) notation to represent where the fields are nested: @@ -122,7 +122,7 @@ Beta notices should not have newlines. beta: Reusing these fields in this location is currently considered beta. ``` -The `short_override` marker can optionally be used along with `at` and `as` to set the short description of the nested field, instead of defaulting to the top-level fieldset's short description. +The `short_override` marker can optionally be used along with `at` and `as` to set the short description of the nested field, instead of defaulting to the top-level fieldset's short description. Like short, descriptions must not have newlines. ``` @@ -180,7 +180,8 @@ Supported keys to describe expected values for a field ``` - accepted\_values: list of dictionaries with the 'name' and 'description' of the expected values. - Optionally, entries in this list can specify 'expected\_event\_types'. + Optionally, entries in this list can specify 'expected\_event\_types'. The `beta` field is also + allowed here and will add a beta marker to the allowed value in the ECS categorization docs. - expected\_event\_types: list of expected "event.type" values to use in association with that category. diff --git a/scripts/templates/field_values.j2 b/scripts/templates/field_values.j2 index 488a2793e9..86576c6930 100644 --- a/scripts/templates/field_values.j2 +++ b/scripts/templates/field_values.j2 @@ -41,7 +41,13 @@ once the appropriate categorization values are published, in a later release. {% for value_details in field['allowed_values'] %} [float] [[ecs-{{ field['dashed_name'] }}-{{ value_details['name'] }}]] -==== {{ value_details['name'] }} +==== {{ value_details['name'] -}} + +{% if value_details['beta'] %} + +beta:[ {{ value_details['beta'] }} ] + +{%- endif %} {{ value_details['description']|replace("\n", "\n\n") }} diff --git a/scripts/tests/test_asciidoc_fields.py b/scripts/tests/test_asciidoc_fields.py index 2fbec15e84..1851fc95fe 100644 --- a/scripts/tests/test_asciidoc_fields.py +++ b/scripts/tests/test_asciidoc_fields.py @@ -15,6 +15,7 @@ class TestGeneratorsAsciiFields(unittest.TestCase): def setUp(self): self.foo_fieldset = self.dummy_fieldset() + self.event_dummy_nested_fields = self.dummy_nested_event_fieldset() def dummy_fieldset(self): return { @@ -42,6 +43,7 @@ def dummy_fieldset(self): ] }, 'foo.id': { + 'beta': 'this is a beta field', 'dashed_name': 'foo-id', 'description': 'Unique ID of the foo.', 'example': 'foo123', @@ -94,6 +96,75 @@ def dummy_fieldset(self): 'type': 'group' } + def dummy_nested_event_fieldset(self): + return { + 'event': { + 'name': 'event', + 'description': 'description', + 'type': 'group', + 'title': 'Event', + 'prefix': 'event.', + 'fields': { + 'event.kind': { + 'dashed_name': 'event-kind', + 'name': 'kind', + 'allowed_values': [{ + 'description': 'fluffy foo', + 'name': 'fluffy', + }, + { + 'description': 'coarse foo', + 'name': 'coarse', + 'beta': 'beta', + } + ] + }, + 'event.category': { + 'dashed_name': 'event-category', + 'name': 'category', + 'allowed_values': [{ + 'description': 'fluffy foo', + 'name': 'fluffy', + }, + { + 'description': 'coarse foo', + 'name': 'coarse', + 'beta': 'beta', + } + ] + }, + 'event.type': { + 'dashed_name': 'event-type', + 'name': 'type', + 'allowed_values': [{ + 'description': 'fluffy foo', + 'name': 'fluffy', + }, + { + 'description': 'coarse foo', + 'name': 'coarse', + 'beta': 'beta', + } + ] + }, + 'event.outcome': { + 'dashed_name': 'event-outcome', + 'name': 'outcome', + 'allowed_values': [{ + 'description': 'fluffy foo', + 'name': 'fluffy', + }, + { + 'description': 'coarse foo', + 'name': 'coarse', + 'beta': 'beta', + } + ] + } + } + } + } + def test_validate_sort_fieldset(self): sorted_foo_fields = asciidoc_fields.sort_fields(self.foo_fieldset) #import pdb;pdb.set_trace() @@ -137,6 +208,10 @@ def test_check_for_usage_doc_false(self): foo_name = self.foo_fieldset.get('name') self.assertFalse(asciidoc_fields.check_for_usage_doc(foo_name, usage_file_list=usage_files)) + def test_check_for_page_field_value_rendering(self): + rendered_field_values = asciidoc_fields.page_field_values(self.event_dummy_nested_fields) + self.assertIn('beta', rendered_field_values) + if __name__ == '__main__': unittest.main()