Better project tooling for snippets

[jack-berg]

Up till now, we use kitchen-sink.yaml as a blunt instrument to:

• Demonstrate the full configuration surface area of the schema
• Validate that the schema works as we expect (i.e. make validate-examples)

This is results in a variety of problems:

• kitchen-sink.yaml is huge!
• Despite our best effort, kitchen-sink.yaml can't express all the configurable surface area. For example, see Add schema for composite sampler #390 using bits of the parent based sampler configuration, which has 5 configurable sampler properties, to express a new sampler.
• kitchen-sink.yaml configuration is often nonsensical, as a result of the effort to document all the surface area.
• kitchen-sink.yaml is annotated with comments generated from the JSON schema and meta schema, which is good for consistency, but limits our ability to convey bits of information about a specific example to users.

I think what we really need is:

• A directory of snippets, e.g. /snippets
• Where each file in /snippets contains a narrow demonstration of a particular piece of the larger schema
• With build tooling which validates that each file adheres to the particular type it is demonstrating, leveraging a file naming convention of the form {type}_{snippet_description}.yaml with build tooling validating according to the {type} extracted from the file name.
• Where snippets do not contain generated comments from the JSON schema and meta schema, but instead only include ad-hoc comments where needed
• The generated schema-docs.md could leverage these snippets to detect usages of each type, and either link over to those snippets or directly embed their contents in the markdown.
• And where this tooling ultimately allows kitchen-sink.yaml to be deleted, as it is essentially decomposed into a bunch of smaller focussed pieces.

[marcalff]

Up till now, we use kitchen-sink.yaml as a blunt instrument to:

* Demonstrate the full configuration surface area of the schema

* Validate that the schema works as we expect (i.e. `make validate-examples`)

This is also a torture test for SIG implementations:

https://github.com/open-telemetry/opentelemetry-cpp/blob/main/functional/configuration/shelltests/kitchen-sink.test

[jack-berg]

This is also a torture test for SIG implementations:

Oh yes. We do that in java in a couple of places as well. SIG implementations could leverage snippets to do similar things in principle. Though, there's something nice / tortuous about exercising so much of the schema all at once like kitchen-sink.yaml tests do.

[jack-berg]

With #397 merged, I'll be chip away at converting kitchen-sink.yaml to targeted snippets and ultimately delete it.

[jack-berg]

Need to decide what our policy / phiilosophy is around snippets. As I said in this comment:

Yeah I've been going back and forth about this.. Now that we have a tool for snippets, what should our goal be?
One direction:

• At least one snippet for every type, illustrating the "kitchen sink" of available properties for that type
• Other snippets for popular use cases of the type as needed

But this has some downsides:

• There's a lot of types, so there will be a lot of snippets! Some of them may start to feel repetitive.
• Snippets for different extension points end up scatter around the docs. For example, right now we have snippets for OtlpHttpExporter and ExperimentalOtlpFileExporter, but none for SpanExporter. It may be more useful to aggregate the snippets for the built-in extension plugins in the SDK extension plugin type. I.e. keep all the built-in span exporter snippets in the in SpanExporter type, keep all the built-in sampler snippets in the Sampler type. This would allow readers to see the different type of exporter configuration at a glance, without having to jump around a bunch of places. But it would mean a more nuanced snippet policy than "one snippet for every type".