search

prometheus-community / windows_exporter

Prometheus exporter for Windows machines
MIT License
2.84k stars 680 forks source link

Auto-generate docs from collectors #1504

Open patrickeasters opened 3 months ago

patrickeasters commented 3 months ago

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 commented 3 months ago

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 commented 4 weeks ago

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