Adds an option to render briefs and notes of semconv / attributes groups in markdown

Signed-off-by: Alexander Wert <[email protected]>

Author: AlexanderWert

semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py

@@ -46,6 +46,8 @@ def __init__(self):
         self.is_remove_constraint = False
         self.is_metric_table = False
         self.is_omit_requirement_level = False
+        self.is_render_group_brief = False
+        self.is_render_group_note = False
         self.group_key = ""
         self.enums = []
         self.notes = []
@@ -77,6 +79,8 @@ class MarkdownRenderer:
         "remove_constraints",
         "metric_table",
         "omit_requirement_level",
+        "render_group_brief",
+        "render_group_note",
     ]
 
     prelude = "<!-- semconv {} -->\n"
@@ -206,6 +210,12 @@ def write_table_header(self, output: io.StringIO):
     def to_markdown_attribute_table(
         self, semconv: BaseSemanticConvention, output: io.StringIO
     ):
+        if self.render_ctx.is_render_group_brief:
+            output.write(semconv.brief + "\n\n")
+
+        if self.render_ctx.is_render_group_note:
+            output.write(semconv.note + "\n\n")
+
         attr_to_print = []
         for attr in semconv.attributes_and_templates:
             if self.render_ctx.group_key is not None:
@@ -518,6 +528,12 @@ def _render_group(self, semconv, parameters, output):
         self.render_ctx.is_omit_requirement_level = (
             "omit_requirement_level" in parameters
         )
+        self.render_ctx.is_render_group_brief = (
+            "render_group_brief" in parameters
+        )
+        self.render_ctx.is_render_group_note = (
+            "render_group_note" in parameters
+        )
 
         if self.render_ctx.is_metric_table:
             self.to_markdown_metric_table(semconv, output)

semantic-conventions/src/tests/data/markdown/attribute_group/attribute_group.yaml

@@ -2,7 +2,7 @@ groups:
   - id: attributes
     prefix: "foo"
     type: attribute_group
-    brief: Attribute group
+    brief: Attribute group brief.
     attributes:
       - id: bar
         type: string
@@ -16,6 +16,7 @@ groups:
     extends: attributes
     prefix: "foo"
     brief: Derived attribute group
+    note: This is a groupt note.
     attributes:
       - id: qux
         type: int

semantic-conventions/src/tests/data/markdown/attribute_group/expected.md

@@ -6,3 +6,19 @@
 | `foo.bar` | string | Attribute 1 | `baz` | Recommended: if available |
 | `foo.qux` | int | Attribute 2 | `42` | Conditionally Required: if available |
 <!-- endsemconv -->
+
+<!-- semconv attributes(render_group_brief) -->
+Attribute group brief.
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `foo.bar` | string | Attribute 1 | `baz` | Recommended: if available |
+<!-- endsemconv -->
+
+<!-- semconv derived_attributes(render_group_note) -->
+This is a groupt note.
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `foo.qux` | int | Attribute 2 | `42` | Conditionally Required: if available |
+<!-- endsemconv -->

semantic-conventions/src/tests/data/markdown/attribute_group/input.md

@@ -2,3 +2,9 @@
 
 <!-- semconv span_attribute_group -->
 <!-- endsemconv -->
+
+<!-- semconv attributes(render_group_brief) -->
+<!-- endsemconv -->
+
+<!-- semconv derived_attributes(render_group_note) -->
+<!-- endsemconv -->