Add support for value in documentation

internal/docs/exported_fields.go

@@ -5,19 +5,27 @@
 package docs
 
 import (
+	"errors"
 	"fmt"
 	"sort"
 	"strings"
 
+	"github.com/Masterminds/semver/v3"
+
 	"github.com/elastic/elastic-package/internal/fields"
+	"github.com/elastic/elastic-package/internal/packages"
 )
 
+var semver3_2_3 = semver.MustParse("3.2.3")
+
 type fieldsTableRecord struct {
 	name        string
 	description string
 	aType       string
 	unit        string
 	metricType  string
+	value       string
+	example	    string
 }
 
 var escaper = strings.NewReplacer("*", "\\*", "{", "\\{", "}", "\\}", "<", "\\<", ">", "\\>")
@@ -46,13 +54,37 @@ func renderExportedFields(fieldsParentDir string) (string, error) {
 		builder.WriteString("(no fields available)\n")
 		return builder.String(), nil
 	}
-	renderFieldsTable(&builder, collected)
+
+	packageRoot, found, err := packages.FindPackageRoot()
+	if err != nil {
+		return "", fmt.Errorf("locating package root failed: %w", err)
+	}
+	if !found {
+		return "", errors.New("package root not found, you can only create new data stream in the package context")
+	}
+	manifest, err := packages.ReadPackageManifestFromPackageRoot(packageRoot)
+	if err != nil {
+		return "", fmt.Errorf("failed to read package manifest from \"%s\"", packageRoot)
+	}
+	sv, err := semver.NewVersion(manifest.SpecVersion)
+	if err != nil {
+		return "", fmt.Errorf("failed to obtain spec version from package manifest in \"%s\"", packageRoot)
+	}
+
+	if sv.LessThan(semver3_2_3) {
+		renderFieldsTable(&builder, collected, false, false)
+	} else {
+		renderFieldsTable(&builder, collected, true, true)
+	}
+
 	return builder.String(), nil
 }
 
-func renderFieldsTable(builder *strings.Builder, collected []fieldsTableRecord) {
+func renderFieldsTable(builder *strings.Builder, collected []fieldsTableRecord, includeValues bool, includeExamples bool) {
 	unitsPresent := areUnitsPresent(collected)
 	metricTypesPresent := areMetricTypesPresent(collected)
+	valuesPresent := areValuesPresent(collected)
+	examplePresent := areExamplesPresent(collected)
 
 	builder.WriteString("| Field | Description | Type |")
 	if unitsPresent {
@@ -61,6 +93,12 @@ func renderFieldsTable(builder *strings.Builder, collected []fieldsTableRecord)
 	if metricTypesPresent {
 		builder.WriteString(" Metric Type |")
 	}
+	if valuesPresent && includeValues {
+		builder.WriteString(" Value |")
+	}
+	if examplePresent && includeExamples {
+		builder.WriteString(" Example |")
+	}
 
 	builder.WriteString("\n")
 	builder.WriteString("|---|---|---|")
@@ -70,6 +108,12 @@ func renderFieldsTable(builder *strings.Builder, collected []fieldsTableRecord)
 	if metricTypesPresent {
 		builder.WriteString("---|")
 	}
+	if valuesPresent && includeValues {
+		builder.WriteString("---|")
+	}
+	if examplePresent && includeExamples {
+		builder.WriteString("---|")
+	}
 
 	builder.WriteString("\n")
 	for _, c := range collected {
@@ -84,6 +128,12 @@ func renderFieldsTable(builder *strings.Builder, collected []fieldsTableRecord)
 		if metricTypesPresent {
 			builder.WriteString(fmt.Sprintf(" %s |", c.metricType))
 		}
+		if valuesPresent && includeValues {
+			builder.WriteString(fmt.Sprintf(" %s |", c.value))
+		}
+		if examplePresent && includeExamples {
+			builder.WriteString(fmt.Sprintf(" %s |", c.example))
+		}
 		builder.WriteString("\n")
 	}
 }
@@ -106,6 +156,24 @@ func areMetricTypesPresent(collected []fieldsTableRecord) bool {
 	return false
 }
 
+func areValuesPresent(collected []fieldsTableRecord) bool {
+	for _, c := range collected {
+		if c.value != "" {
+			return true
+		}
+	}
+	return false
+}
+
+func areExamplesPresent(collected []fieldsTableRecord) bool {
+	for _, c := range collected {
+		if c.example != "" {
+			return true
+		}
+	}
+	return false
+}
+
 func collectFieldsFromDefinitions(validator *fields.Validator) []fieldsTableRecord {
 	var records []fieldsTableRecord
 
@@ -130,6 +198,8 @@ func visitFields(namePrefix string, f fields.FieldDefinition, records []fieldsTa
 			aType:       f.Type,
 			unit:        f.Unit,
 			metricType:  f.MetricType,
+			value:       f.Value,
+			example:     f.Example,
 		})
 
 		for _, multiField := range f.MultiFields {

internal/fields/model.go

@@ -27,6 +27,7 @@ type FieldDefinition struct {
 	Unit           string            `yaml:"unit"`
 	MetricType     string            `yaml:"metric_type"`
 	External       string            `yaml:"external"`
+	Example        string            `yaml:"example"`
 	Index          *bool             `yaml:"index"`
 	Enabled        *bool             `yaml:"enabled"`
 	DocValues      *bool             `yaml:"doc_values"`