maint: Generate docs better suited to docs team prefs (#713)

## Which problem is this PR solving?

This tweaks the docs generation code to create documents that are closer
to the needs of the docs team.

## Short description of the changes

- Helper function to generate one line per sentence in generated docs
- Use the helper function
- Reformat the preamble of the rules file
- Regenerate the docs (most of the changed lines are in the .md files)

tools/convert/helpers.go

@@ -43,6 +43,7 @@ func helpers() template.FuncMap {
 		"split":             split,
 		"wci":               wci,
 		"wordwrap":          wordwrap,
+		"wrapForDocs":       wrapForDocs,
 		"yamlf":             yamlf,
 	}
 }
@@ -375,6 +376,14 @@ func wordwrap(s string) string {
 	return strings.Join(output, "\n")
 }
 
+func wrapForDocs(s string) string {
+	paragraphBreak := regexp.MustCompile(`\n\s*\n`)
+	s = paragraphBreak.ReplaceAllString(s, "__PARAGRAPH_BREAK__")
+	sentenceEnd := regexp.MustCompile(`([.?!])\s+|__PARAGRAPH_BREAK__`)
+	s = sentenceEnd.ReplaceAllString(s, "$1\n")
+	return s
+}
+
 // simplistic YAML formatting of a value
 func yamlf(a any) string {
 	switch v := a.(type) {

tools/convert/templates/cfg_docfield.tmpl

@@ -1,11 +1,12 @@
 {{- $field := . -}}
 
+{{- println -}}
 ### `{{ $field.Name }}`
 
-{{ printf "%s %s" $field.Name $field.Summary | wordwrap }}
+{{ printf "%s %s" $field.Name $field.Summary }}
 
 {{ if $field.Description -}}
-{{ $field.Description | wordwrap }}
+{{ $field.Description | wrapForDocs }}
 
 {{- end -}}
 {{- println -}}

tools/convert/templates/cfg_docfile.tmpl

@@ -24,8 +24,7 @@ OTelMetrics:
   APIKey: SetThisToAHoneycombKey
 ```
 
-The remainder of this document describes the sections within the file and the
-fields in each.
+The remainder of this document describes the sections within the file and the fields in each.
 
 ## Table of Contents
 {{ range $file.Groups -}}

tools/convert/templates/cfg_docgroup.tmpl

@@ -4,7 +4,7 @@
 
 ### Section Name: `{{ $group.Name }}`
 
-{{ $group.Description | wordwrap }}
+{{ $group.Description | wrapForDocs }}
 {{- println -}}
 {{- println -}}
 

tools/convert/templates/rules_docfield.tmpl

@@ -1,12 +1,12 @@
 {{- $field := . -}}
 
-### {{ $field.Name }}
+### `{{ $field.Name }}`
 
 {{ if $field.Description -}}
-{{ $field.Description | wordwrap }}
+{{ $field.Description | wrapForDocs }}
 
 {{- else -}}
-{{ printf "%s %s" $field.Name $field.Summary | wordwrap }}
+{{ printf "%s %s" $field.Name $field.Summary }}
 
 {{- end }}
 

tools/convert/templates/rules_docfile.tmpl

@@ -27,24 +27,21 @@ Samplers:
 
 Name: `RulesVersion`
 
-This is a required parameter used to verify the version of
-the rules file. It must be set to 2.
+This is a required parameter used to verify the version of the rules file.
+It must be set to 2.
 
 Name: `Samplers`
 
-Samplers is a mapping of targets to samplers. Each target is a
-Honeycomb environment (or, for classic keys, a dataset). The value is
-the sampler to use for that target. The target called `__default__`
-will be used for any target that is not explicitly listed. A
-`__default__` target is required.
-The targets are determined by examining the API key used to send the
-trace. If the API key is a 'classic' key (which is a 32-character
-hexadecimal value), the specified dataset name is used as the target.
-If the API key is a new-style key (20-23 alphanumeric characters), the
-key's environment name is used as the target.
+Samplers is a mapping of targets to samplers.
+Each target is a Honeycomb environment (or, for classic keys, a dataset).
+The value is the sampler to use for that target.
+The target called `__default__` will be used for any target that is not explicitly listed.
+A `__default__` target is required.
+The targets are determined by examining the API key used to send the trace.
+If the API key is a 'classic' key (which is a 32-character hexadecimal value), the specified dataset name is used as the target.
+If the API key is a new-style key (20-23 alphanumeric characters), the key's environment name is used as the target.
 
-The remainder of this document describes the samplers that can be used within
-the `Samplers` section and the fields that control their behavior.
+The remainder of this document describes the samplers that can be used within the `Samplers` section and the fields that control their behavior.
 
 ## Table of Contents
 {{ range $file.Groups -}}

tools/convert/templates/rules_docgroup.tmpl

@@ -4,7 +4,7 @@
 
 ### Name: `{{ $group.Name }}`
 
-{{ $group.Description | wordwrap }}
+{{ $group.Description | wrapForDocs }}
 {{- println -}}
 {{- println -}}