chore: Embed sample configurations into README for aggregators (#11190)

Makefile

@@ -119,25 +119,18 @@ versioninfo:
 build_generator:
 	go build -o ./tools/readme_config_includer/generator ./tools/readme_config_includer/generator.go
 
-insert_config_to_readme_%: build_generator
+embed_readme_%: build_generator
 	go generate -run="readme_config_includer/generator$$" ./plugins/$*/...
 
-generate_plugins_%: build_generator
-	go generate -run="plugindata/main.go$$" ./plugins/$*/...
-
 .PHONY: generate
-generate: insert_config_to_readme_inputs insert_config_to_readme_outputs insert_config_to_readme_processors generate_plugins_aggregators
-
-.PHONY: generate-clean
-generate-clean:
-	go generate -run="plugindata/main.go --clean" ./plugins/aggregators/...
+generate: embed_readme_inputs embed_readme_outputs embed_readme_processors embed_readme_aggregators
 
 .PHONY: build
 build:
 	go build -ldflags "$(LDFLAGS)" ./cmd/telegraf
 
 .PHONY: telegraf
-telegraf: generate build generate-clean
+telegraf: generate build
 
 # Used by dockerfile builds
 .PHONY: go-install
@@ -340,7 +333,7 @@ darwin-arm64:
 include_packages := $(mips) $(mipsel) $(arm64) $(amd64) $(static) $(armel) $(armhf) $(riscv64) $(s390x) $(ppc64le) $(i386) $(windows) $(darwin-amd64) $(darwin-arm64)
 
 .PHONY: package
-package: generate $(include_packages) generate-clean
+package: generate $(include_packages)
 
 .PHONY: $(include_packages)
 $(include_packages):

docs/AGGREGATORS.md

@@ -9,10 +9,11 @@ This section is for developers who want to create a new aggregator plugin.
   register themselves.  See below for a quick example.
 * To be available within Telegraf itself, plugins must add themselves to the
   `github.com/influxdata/telegraf/plugins/aggregators/all/all.go` file.
-* Each plugin requires a file called `<plugin_name>_sample_config.go`, where `<plugin_name>` is replaced with the actual plugin name.
-  Copy the [example template](#sample-configuration-template) into this file, also updating `<plugin_name>` were appropriate.
-  This file is automatically updated during the build process to include the sample configuration from the `README.md`.
+* Each plugin requires a file called `sample.conf` containing the sample configuration
+  for the plugin in TOML format.
   Please consult the [Sample Config][] page for the latest style guidelines.
+* Each plugin `README.md` file should include the `sample.conf` file in a section
+  describing the configuration by specifying a `toml` section in the form `toml @sample.conf`. The specified file(s) are then injected automatically into the Readme.
 * The Aggregator plugin will need to keep caches of metrics that have passed
   through it. This should be done using the builtin `HashID()` function of
   each metric.
@@ -22,17 +23,22 @@ This section is for developers who want to create a new aggregator plugin.
 ### Aggregator Plugin Example
 
 ```go
-//go:generate go run ../../../tools/generate_plugindata/main.go
-//go:generate go run ../../../tools/generate_plugindata/main.go --clean
+//go:generate ../../../tools/readme_config_includer/generator
 package min
 
 // min.go
 
 import (
+    _ "embed"
+
     "github.com/influxdata/telegraf"
     "github.com/influxdata/telegraf/plugins/aggregators"
 )
 
+// DO NOT REMOVE THE NEXT TWO LINES! This is required to embedd the sampleConfig data.
+//go:embed sample.conf
+var sampleConfig string
+
 type Min struct {
     // caches for metric fields, names, and tags
     fieldCache map[uint64]map[string]float64
@@ -46,6 +52,10 @@ func NewMin() telegraf.Aggregator {
     return m
 }
 
+func (*Min) SampleConfig() string {
+    return sampleConfig
+}
+
 func (m *Min) Init() error {
     return nil
 }
@@ -112,20 +122,3 @@ func init() {
     })
 }
 ```
-
-### Sample Configuration Template
-
-```go
-//go:generate go run ../../../tools/generate_plugindata/main.go
-//go:generate go run ../../../tools/generate_plugindata/main.go --clean
-// DON'T EDIT; This file is used as a template by tools/generate_plugindata
-package <plugin_package>
-
-func (k *<plugin_struct>) SampleConfig() string {
-    return `{{ .SampleConfig }}`
-}
-```
-
-[telegraf.Aggregator]: https://godoc.org/github.com/influxdata/telegraf#Aggregator
-[Sample Config]: https://github.com/influxdata/telegraf/blob/master/docs/developers/SAMPLE_CONFIG.md
-[Code Style]: https://github.com/influxdata/telegraf/blob/master/docs/developers/CODE_STYLE.md

docs/INPUTS.md

@@ -15,10 +15,11 @@ and submit new inputs.
   themselves.  See below for a quick example.
 - Input Plugins must be added to the
   `github.com/influxdata/telegraf/plugins/inputs/all/all.go` file.
-- Each plugin requires a file called `<plugin_name>_sample_config.go`, where `<plugin_name>` is replaced with the actual plugin name.
-  Copy the [example template](#sample-configuration-template) into this file, also updating `<plugin_name>` were appropriate.
-  This file is automatically updated during the build process to include the sample configuration from the `README.md`.
+- Each plugin requires a file called `sample.conf` containing the sample
+  configuration  for the plugin in TOML format.
   Please consult the [Sample Config][] page for the latest style guidelines.
+- Each plugin `README.md` file should include the `sample.conf` file in a section
+  describing the configuration by specifying a `toml` section in the form `toml @sample.conf`. The specified file(s) are then injected automatically into the Readme.
 - Follow the recommended [Code Style][].
 
 Let's say you've written a plugin that emits metrics about processes on the
@@ -27,20 +28,29 @@ current host.
 ## Input Plugin Example
 
 ```go
-//go:generate go run ../../../tools/generate_plugindata/main.go
-//go:generate go run ../../../tools/generate_plugindata/main.go --clean
+//go:generate ../../../tools/readme_config_includer/generator
 package simple
 
 import (
+    _ "embed"
+
     "github.com/influxdata/telegraf"
     "github.com/influxdata/telegraf/plugins/inputs"
 )
 
+// DO NOT REMOVE THE NEXT TWO LINES! This is required to embedd the sampleConfig data.
+//go:embed sample.conf
+var sampleConfig string
+
 type Simple struct {
     Ok  bool            `toml:"ok"`
     Log telegraf.Logger `toml:"-"`
 }
 
+func (*Simple) SampleConfig() string {
+    return sampleConfig
+}
+
 // Init is for setup, and validating config.
 func (s *Simple) Init() error {
     return nil
@@ -61,17 +71,6 @@ func init() {
 }
 ```
 
-```go
-//go:generate go run ../../../tools/generate_plugindata/main.go
-//go:generate go run ../../../tools/generate_plugindata/main.go --clean
-// DON'T EDIT; This file is used as a template by tools/generate_plugindata
-package <plugin_package>
-
-func (k *<plugin_struct>) SampleConfig() string {
-    return `{{ .SampleConfig }}`
-}
-```
-
 ### Development
 
 - Run `make static` followed by `make plugin-[pluginName]` to spin up a docker

docs/OUTPUTS.md

@@ -11,31 +11,41 @@ similar constructs.
   themselves.  See below for a quick example.
 - To be available within Telegraf itself, plugins must add themselves to the
   `github.com/influxdata/telegraf/plugins/outputs/all/all.go` file.
-- Each plugin requires a file called `<plugin_name>_sample_config.go`, where `<plugin_name>` is replaced with the actual plugin name.
-  Copy the [example template](#sample-configuration-template) into this file, also updating `<plugin_name>` were appropriate.
-  This file is automatically updated during the build process to include the sample configuration from the `README.md`.
+- Each plugin requires a file called `sample.conf` containing the sample
+  configuration  for the plugin in TOML format.
   Please consult the [Sample Config][] page for the latest style guidelines.
+- Each plugin `README.md` file should include the `sample.conf` file in a section
+  describing the configuration by specifying a `toml` section in the form `toml @sample.conf`. The specified file(s) are then injected automatically into the Readme.
 - Follow the recommended [Code Style][].
 
 ## Output Plugin Example
 
 ```go
-//go:generate go run ../../../tools/generate_plugindata/main.go
-//go:generate go run ../../../tools/generate_plugindata/main.go --clean
+//go:generate ../../../tools/readme_config_includer/generator
 package simpleoutput
 
 // simpleoutput.go
 
 import (
+    _ "embed"
+
     "github.com/influxdata/telegraf"
     "github.com/influxdata/telegraf/plugins/outputs"
 )
 
+// DO NOT REMOVE THE NEXT TWO LINES! This is required to embedd the sampleConfig data.
+//go:embed sample.conf
+var sampleConfig string
+
 type Simple struct {
     Ok  bool            `toml:"ok"`
     Log telegraf.Logger `toml:"-"`
 }
 
+func (*Simple) SampleConfig() string {
+    return sampleConfig
+}
+
 // Init is for setup, and validating config.
 func (s *Simple) Init() error {
     return nil
@@ -68,19 +78,6 @@ func init() {
 
 ```
 
-### Sample Configuration Template
-
-```go
-//go:generate go run ../../../tools/generate_plugindata/main.go
-//go:generate go run ../../../tools/generate_plugindata/main.go --clean
-// DON'T EDIT; This file is used as a template by tools/generate_plugindata
-package <plugin_package>
-
-func (k *<plugin_struct>) SampleConfig() string {
-    return `{{ .SampleConfig }}`
-}
-```
-
 ## Data Formats
 
 Some output plugins, such as the [file][] plugin, can write in any supported

docs/PROCESSORS.md

@@ -9,32 +9,41 @@ This section is for developers who want to create a new processor plugin.
   themselves.  See below for a quick example.
 * To be available within Telegraf itself, plugins must add themselves to the
   `github.com/influxdata/telegraf/plugins/processors/all/all.go` file.
-* Each plugin requires a file called `<plugin_name>_sample_config.go`, where `<plugin_name>` is replaced with the actual plugin name.
-  Copy the [example template](#sample-configuration-template) into this file, also updating `<plugin_name>` were appropriate.
-  This file is automatically updated during the build process to include the sample configuration from the `README.md`.
+* Each plugin requires a file called `sample.conf` containing the sample
+  configuration  for the plugin in TOML format.
   Please consult the [Sample Config][] page for the latest style guidelines.
+* Each plugin `README.md` file should include the `sample.conf` file in a section
+  describing the configuration by specifying a `toml` section in the form `toml @sample.conf`. The specified file(s) are then injected automatically into the Readme.
 * Follow the recommended [Code Style][].
 
 ## Processor Plugin Example
 
 ```go
-//go:generate go run ../../../tools/generate_plugindata/main.go
-//go:generate go run ../../../tools/generate_plugindata/main.go --clean
+//go:generate ../../../tools/readme_config_includer/generator
 package printer
 
 // printer.go
 
 import (
+    _ "embed"
     "fmt"
 
     "github.com/influxdata/telegraf"
     "github.com/influxdata/telegraf/plugins/processors"
 )
 
+// DO NOT REMOVE THE NEXT TWO LINES! This is required to embedd the sampleConfig data.
+//go:embed sample.conf
+var sampleConfig string
+
 type Printer struct {
     Log telegraf.Logger `toml:"-"`
 }
 
+func (*Printer) SampleConfig() string {
+    return sampleConfig
+}
+
 // Init is for setup, and validating config.
 func (p *Printer) Init() error {
     return nil
@@ -54,19 +63,6 @@ func init() {
 }
 ```
 
-### Sample Configuration Template
-
-```go
-//go:generate go run ../../../tools/generate_plugindata/main.go
-//go:generate go run ../../../tools/generate_plugindata/main.go --clean
-// DON'T EDIT; This file is used as a template by tools/generate_plugindata
-package <plugin_package>
-
-func (k *<plugin_struct>) SampleConfig() string {
-    return `{{ .SampleConfig }}`
-}
-```
-
 ## Streaming Processors
 
 Streaming processors are a new processor type available to you. They are
@@ -88,21 +84,31 @@ Some differences from classic Processors:
 ## Streaming Processor Example
 
 ```go
+//go:generate ../../../tools/readme_config_includer/generator
 package printer
 
 // printer.go
 
 import (
+    _ "embed"
     "fmt"
 
     "github.com/influxdata/telegraf"
     "github.com/influxdata/telegraf/plugins/processors"
 )
 
+// DO NOT REMOVE THE NEXT TWO LINES! This is required to embedd the sampleConfig data.
+//go:embed sample.conf
+var sampleConfig string
+
 type Printer struct {
     Log telegraf.Logger `toml:"-"`
 }
 
+func (*Printer) SampleConfig() string {
+    return sampleConfig
+}
+
 // Init is for setup, and validating config.
 func (p *Printer) Init() error {
     return nil

plugins/aggregators/basicstats/README.md

@@ -5,7 +5,7 @@ emitting the aggregate every `period` seconds.
 
 ## Configuration
 
-```toml
+```toml @sample.conf
 # Keep the aggregate basicstats of each metric passing through.
 [[aggregators.basicstats]]
   ## The period on which to flush & clear the aggregator.

plugins/aggregators/basicstats/basicstats.go

@@ -1,13 +1,19 @@
+//go:generate ../../../tools/readme_config_includer/generator
 package basicstats
 
 import (
+	_ "embed"
 	"math"
 	"time"
 
 	"github.com/influxdata/telegraf"
 	"github.com/influxdata/telegraf/plugins/aggregators"
 )
 
+// DO NOT REMOVE THE NEXT TWO LINES! This is required to embedd the sampleConfig data.
+//go:embed sample.conf
+var sampleConfig string
+
 type BasicStats struct {
 	Stats []string `toml:"stats"`
 	Log   telegraf.Logger
@@ -57,6 +63,10 @@ type basicstats struct {
 	TIME     time.Time //intermediate value for rate
 }
 
+func (*BasicStats) SampleConfig() string {
+	return sampleConfig
+}
+
 func (b *BasicStats) Add(in telegraf.Metric) {
 	id := in.HashID()
 	if _, ok := b.cache[id]; !ok {

plugins/aggregators/derivative/README.md

@@ -137,7 +137,7 @@ Using `max_roll_over` with a value greater 0 may be important, if you need to de
 
 ## Configuration
 
-```toml
+```toml @sample.conf
 # Calculates a derivative for every field.
 [[aggregators.derivative]]
   ## Specific Derivative Aggregator Arguments: