Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Jun 12, 2023
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
794 changes: 349 additions & 445 deletions config.md
View file
Open in desktop

Large diffs are not rendered by default.

836 changes: 329 additions & 507 deletions rules.md
View file
Open in desktop

Large diffs are not rendered by default.

9 changes: 9 additions & 0 deletions tools/convert/helpers.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ func helpers() template.FuncMap {
"split": split,
"wci": wci,
"wordwrap": wordwrap,
"wrapForDocs": wrapForDocs,
"yamlf": yamlf,
}
}
Expand Down Expand Up @@ -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) {
Expand Down
5 changes: 3 additions & 2 deletions tools/convert/templates/cfg_docfield.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 -}}
Expand Down
3 changes: 1 addition & 2 deletions tools/convert/templates/cfg_docfile.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 -}}
Expand Down
2 changes: 1 addition & 1 deletion tools/convert/templates/cfg_docgroup.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

### Section Name: `{{ $group.Name }}`

{{ $group.Description | wordwrap }}
{{ $group.Description | wrapForDocs }}
{{- println -}}
{{- println -}}

Expand Down
6 changes: 3 additions & 3 deletions tools/convert/templates/rules_docfield.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 }}

Expand Down
25 changes: 11 additions & 14 deletions tools/convert/templates/rules_docfile.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 -}}
Expand Down
2 changes: 1 addition & 1 deletion tools/convert/templates/rules_docgroup.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

### Name: `{{ $group.Name }}`

{{ $group.Description | wordwrap }}
{{ $group.Description | wrapForDocs }}
{{- println -}}
{{- println -}}

Expand Down