Auto-generate docs from collectors

[patrickeasters]

I've noticed a handful of times that Windows Exporter docs in this repo don't accurately reflect the metrics in the collector code. It's not uncommon to find metrics that are collected but not documented. Some collectors list the fully qualified metric name (i.e. include windows_<collector>_), whereas others don't. Some descriptions in the docs don't match the metric's help text.

Out of curiosity, I played around and was able to use the reflect package to load all the collectors and iterate over the Prometheus descriptors from the codebase. Would there be any interest in auto-generating the doc pages from the collector code? I'm willing to work on a PR for this, but wanted to gauge interest before putting more time into it.

That leads me to a few questions:

1. Would this be considered helpful/useful?
2. How do we want to handle cases where docs have different descriptions versus the Prometheus "help" text?
3. What would be an ideal flow for updating docs? Are contributors expected to run a make target to update docs as part of their PR or should this just happen via GitHub actions after a merge to master?

[jkroepke]

Hi there,

if possible, I would really appreciate such an automation. In Addition to reflect, I would also suggest to use https://pkg.go.dev/go/doc and use some go doc as source, if nessary.

How do we want to handle cases where docs have different descriptions versus the Prometheus "help" text?

Is there anything that block us for unify the description on both places?

What would be an ideal flow for updating docs? Are contributors expected to run a make target to update docs as part of their PR or should this just happen via GitHub actions after a merge to master?

I expect that users should update the docs as part of a PR and there is action that validates that. I personally prefer go generate over make target.

[andonovski]

Speaking as an end user, this kind of automation would really helpful.

[github-actions]

This issue has been marked as stale because it has been open for 90 days with no activity. This thread will be automatically closed in 30 days if no further activity occurs.