Add support for value in documentation

internal/docs/exported_fields.go

@@ -9,20 +9,27 @@ import (
 	"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.4.0")
+
 type fieldsTableRecord struct {
 	name        string
 	description string
 	aType       string
 	unit        string
 	metricType  string
+	value       string
+	example	    string
 }
 
 var escaper = strings.NewReplacer("*", "\\*", "{", "\\{", "}", "\\}", "<", "\\<", ">", "\\>")
 
-func renderExportedFields(fieldsParentDir string) (string, error) {
+func renderExportedFields(fieldsParentDir string, pkgManifest *packages.PackageManifest) (string, error) {
 	injectOptions := fields.InjectFieldsOptions{
 		// Keep External parameter when rendering fields, so we can render
 		// documentation for empty groups imported from ECS, for backwards compatibility.
@@ -46,13 +53,27 @@ func renderExportedFields(fieldsParentDir string) (string, error) {
 		builder.WriteString("(no fields available)\n")
 		return builder.String(), nil
 	}
-	renderFieldsTable(&builder, collected)
+
+	sv, err := semver.NewVersion(pkgManifest.SpecVersion)
+	if err != nil {
+		return "", fmt.Errorf("failed to obtain spec version from package manifest: %w", err)
+	}
+
+	renderExamples := true
+	if sv.LessThan(semver3_2_3) {
+		renderExamples = false
+	}
+
+	renderFieldsTable(&builder, collected, renderExamples)
+
 	return builder.String(), nil
 }
 
-func renderFieldsTable(builder *strings.Builder, collected []fieldsTableRecord) {
+func renderFieldsTable(builder *strings.Builder, collected []fieldsTableRecord, includeExamples bool) {
 	unitsPresent := areUnitsPresent(collected)
 	metricTypesPresent := areMetricTypesPresent(collected)
+	examplePresent := areExamplesPresent(collected)
+	valuesPresent := areValuesPresent(collected)
 
 	builder.WriteString("| Field | Description | Type |")
 	if unitsPresent {
@@ -61,6 +82,9 @@ func renderFieldsTable(builder *strings.Builder, collected []fieldsTableRecord)
 	if metricTypesPresent {
 		builder.WriteString(" Metric Type |")
 	}
+	if (examplePresent || valuesPresent)  && includeExamples {
+		builder.WriteString(" Example |")
+	}
 
 	builder.WriteString("\n")
 	builder.WriteString("|---|---|---|")
@@ -70,6 +94,9 @@ func renderFieldsTable(builder *strings.Builder, collected []fieldsTableRecord)
 	if metricTypesPresent {
 		builder.WriteString("---|")
 	}
+	if (examplePresent || valuesPresent) && includeExamples { // Check whether there are examples to render or whether fields are constants
+		builder.WriteString("---|")
+	}
 
 	builder.WriteString("\n")
 	for _, c := range collected {
@@ -84,6 +111,13 @@ func renderFieldsTable(builder *strings.Builder, collected []fieldsTableRecord)
 		if metricTypesPresent {
 			builder.WriteString(fmt.Sprintf(" %s |", c.metricType))
 		}
+		if (examplePresent || valuesPresent) && includeExamples {
+			if c.aType == "constant_keyword" {
+				builder.WriteString(fmt.Sprintf(" %s |", c.value))
+			} else {
+				builder.WriteString(fmt.Sprintf(" %s |", c.example))
+			}
+		}
 		builder.WriteString("\n")
 	}
 }
@@ -106,6 +140,24 @@ func areMetricTypesPresent(collected []fieldsTableRecord) bool {
 	return false
 }
 
+func areValuesPresent(collected []fieldsTableRecord) bool {
+	for _, c := range collected {
+		if c.aType == "constant_keyword" && 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 +182,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/docs/readme.go

@@ -191,11 +191,15 @@ func renderReadme(fileName, packageRoot, templatePath string, linksMap linkMap)
 			return renderSampleEvent(packageRoot, "")
 		},
 		"fields": func(args ...string) (string, error) {
+			manifest, err := packages.ReadPackageManifestFromPackageRoot(packageRoot)
+			if err != nil {
+				return "", fmt.Errorf("reading package manifest failed (path: %s): %w", packageRoot, err)
+			}
 			if len(args) > 0 {
 				dataStreamPath := filepath.Join(packageRoot, "data_stream", args[0])
-				return renderExportedFields(dataStreamPath)
+				return renderExportedFields(dataStreamPath, manifest)
 			}
-			return renderExportedFields(packageRoot)
+			return renderExportedFields(packageRoot, manifest)
 		},
 		"url": func(args ...string) (string, error) {
 			options := linkOptions{}

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"`

test/packages/parallel/nginx/manifest.yml

@@ -1,4 +1,4 @@
-format_version: 1.0.0
+format_version: 3.4.0
 name: nginx
 title: Nginx
 version: 999.999.999