Add support for markdown generation

[pmcollins]

This change contains a CLI tool, called 'docsgen', that generates markdown files for collector
components. The markdown files present the configuration metadata extracted by the configschema
API in a human readable form that can be used to manually configure the collector.

This change also makes some modifications to the package formerly knows as schemagen, renaming
it to configschema and exporting some things, because it no longer generates a schema yaml file, but
rather provides an equivalent API used by docsgen.

Also, this PR includes one sample, generated .md document: receiver/otlpreceiver/config.md

[tigrannajaryan]

This is great!

Can you please validate that this approach will work correctly for components imported from other repositories? For example we want OTLP receiver (which is in this repo) documentation in Collector contrib repo too.

[pmcollins]

This is great!

Can you please validate that this approach will work correctly for components imported from other repositories? For example we want OTLP receiver (which is in this repo) documentation in Collector contrib repo too.

Thanks Tigran. So I experimented a bit, and the docsgen API will work, with minor modifications, when called from a separate repo (e.g. contrib), for components that live in that repo. For components that live in a separate repo, we will need to be able to map instances of configuration types (e.g. otlpreceiver.Config) to the locations of their source code (to extract the comments), which appears to be doable. Can be done in a separate PR to keep this one smaller.

[tigrannajaryan]

This is great!
Can you please validate that this approach will work correctly for components imported from other repositories? For example we want OTLP receiver (which is in this repo) documentation in Collector contrib repo too.

Thanks Tigran. So I experimented a bit, and the docsgen API will work, with minor modifications, when called from a separate repo (e.g. contrib), for components that live in that repo. For components that live in a separate repo, we will need to be able to map instances of configuration types (e.g. otlpreceiver.Config) to the locations of their source code (to extract the comments), which appears to be doable. Can be done in a separate PR to keep this one smaller.

Sounds good, let's finalize this PR and then improve it. We should aim to replace READMEs by this approach.

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[tigrannajaryan]

@pmcollins is this ready for review?

[pmcollins]

@pmcollins is this ready for review?

This is ready for review now. : )

[tigrannajaryan]

This looks good to me. @bogdandrutu thoughts?

[bogdandrutu]

I like it overall, looked only at the result md and added some suggestions, I trust @tigrannajaryan that he reviewed the code that generates the md

[pmcollins]

Thanks for reviewing @tigrannajaryan and @bogdandrutu 🙇
Any remaining questions/comments/concerns?

[tigrannajaryan]

LGTM. Please rebase from main.

[pmcollins]

LGTM. Please rebase from main.

Sure, done.

[tigrannajaryan]

Thanks @pmcollins !