docs: reorganize documentation directory structure

Makefile

@@ -54,13 +54,13 @@ doccheck: generate validate-template
 	@echo "- Checking if the generated documentation is up to date..."
 	@git diff --exit-code
 	@echo "- Checking if the documentation is in sync with the code..."
-	@grep -hoE -d skip '\| kube_[^ |]+' docs/* --exclude=README.md | sed -E 's/\| //g' | sort -u > documented_metrics
+	@grep -rhoE '\| kube_[^ |]+' docs/metrics/* --exclude=README.md | sed -E 's/\| //g' | sort -u > documented_metrics
 	@find internal/store -type f -not -name '*_test.go' -exec sed -nE 's/.*"(kube_[^"]+)".*/\1/p' {} \; | sort -u > code_metrics
 	@diff -u0 code_metrics documented_metrics || (echo "ERROR: Metrics with - are present in code but missing in documentation, metrics with + are documented but not found in code."; exit 1)
 	@echo OK
 	@rm -f code_metrics documented_metrics
 	@echo "- Checking for orphan documentation files"
-	@cd docs; for doc in *.md; do if [ "$$doc" != "README.md" ] && ! grep -q "$$doc" *.md; then echo "ERROR: No link to documentation file $${doc} detected"; exit 1; fi; done
+	@cd docs; for doc in $$(find metrics/* -name '*.md' | sed 's/.*\///'); do if [ "$$doc" != "README.md" ] && ! grep -q "$$doc" *.md; then echo "ERROR: No link to documentation file $${doc} detected"; exit 1; fi; done
 	@echo OK
 
 build-local:

README.md

@@ -204,7 +204,7 @@ In a 100 node cluster scaling test the latency numbers were as follows:
 
 ### A note on costing
 
-By default, kube-state-metrics exposes several metrics for events across your cluster. If you have a large number of frequently-updating resources on your cluster, you may find that a lot of data is ingested into these metrics. This can incur high costs on some cloud providers. Please take a moment to [configure what metrics you'd like to expose](docs/cli-arguments.md), as well as consult the documentation for your Kubernetes environment in order to avoid unexpectedly high costs.
+By default, kube-state-metrics exposes several metrics for events across your cluster. If you have a large number of frequently-updating resources on your cluster, you may find that a lot of data is ingested into these metrics. This can incur high costs on some cloud providers. Please take a moment to [configure what metrics you'd like to expose](docs/developer/cli-arguments.md), as well as consult the documentation for your Kubernetes environment in order to avoid unexpectedly high costs.
 
 ### kube-state-metrics vs. metrics-server
 
@@ -387,7 +387,7 @@ spec:
           - '--namespaces=project1'
 ```
 
-For the full list of arguments available, see the documentation in [docs/cli-arguments.md](./docs/cli-arguments.md)
+For the full list of arguments available, see the documentation in [docs/developer/cli-arguments.md](./docs/developer/cli-arguments.md)
 
 #### Helm Chart
 

README.md.tpl

@@ -205,7 +205,7 @@ In a 100 node cluster scaling test the latency numbers were as follows:
 
 ### A note on costing
 
-By default, kube-state-metrics exposes several metrics for events across your cluster. If you have a large number of frequently-updating resources on your cluster, you may find that a lot of data is ingested into these metrics. This can incur high costs on some cloud providers. Please take a moment to [configure what metrics you'd like to expose](docs/cli-arguments.md), as well as consult the documentation for your Kubernetes environment in order to avoid unexpectedly high costs.
+By default, kube-state-metrics exposes several metrics for events across your cluster. If you have a large number of frequently-updating resources on your cluster, you may find that a lot of data is ingested into these metrics. This can incur high costs on some cloud providers. Please take a moment to [configure what metrics you'd like to expose](docs/developer/cli-arguments.md), as well as consult the documentation for your Kubernetes environment in order to avoid unexpectedly high costs.
 
 ### kube-state-metrics vs. metrics-server
 
@@ -388,7 +388,7 @@ spec:
           - '--namespaces=project1'
 ```
 
-For the full list of arguments available, see the documentation in [docs/cli-arguments.md](./docs/cli-arguments.md)
+For the full list of arguments available, see the documentation in [docs/developer/cli-arguments.md](./docs/developer/cli-arguments.md)
 
 #### Helm Chart
 

docs/README.md

@@ -32,44 +32,44 @@ See each file for specific documentation about the exposed metrics:
 
 ### Default Resources
 
-* [CertificateSigningRequest Metrics](certificatesigningrequest-metrics.md)
-* [ConfigMap Metrics](configmap-metrics.md)
-* [CronJob Metrics](cronjob-metrics.md)
-* [DaemonSet Metrics](daemonset-metrics.md)
-* [Deployment Metrics](deployment-metrics.md)
-* [Endpoint Metrics](endpoint-metrics.md)
-* [Horizontal Pod Autoscaler Metrics](horizontalpodautoscaler-metrics.md)
-* [Ingress Metrics](ingress-metrics.md)
-* [Job Metrics](job-metrics.md)
-* [Lease Metrics](lease-metrics.md)
-* [LimitRange Metrics](limitrange-metrics.md)
-* [MutatingWebhookConfiguration Metrics](mutatingwebhookconfiguration-metrics.md)
-* [Namespace Metrics](namespace-metrics.md)
-* [NetworkPolicy Metrics](networkpolicy-metrics.md)
-* [Node Metrics](node-metrics.md)
-* [PersistentVolume Metrics](persistentvolume-metrics.md)
-* [PersistentVolumeClaim Metrics](persistentvolumeclaim-metrics.md)
-* [Pod Disruption Budget Metrics](poddisruptionbudget-metrics.md)
-* [Pod Metrics](pod-metrics.md)
-* [ReplicaSet Metrics](replicaset-metrics.md)
-* [ReplicationController Metrics](replicationcontroller-metrics.md)
-* [ResourceQuota Metrics](resourcequota-metrics.md)
-* [Secret Metrics](secret-metrics.md)
-* [Service Metrics](service-metrics.md)
-* [StatefulSet Metrics](statefulset-metrics.md)
-* [StorageClass Metrics](storageclass-metrics.md)
-* [ValidatingWebhookConfiguration Metrics](validatingwebhookconfiguration-metrics.md)
-* [VolumeAttachment Metrics](volumeattachment-metrics.md)
+* [CertificateSigningRequest Metrics](metrics/auth/certificatesigningrequest-metrics.md)
+* [ConfigMap Metrics](metrics/storage/configmap-metrics.md)
+* [CronJob Metrics](metrics/workload/cronjob-metrics.md)
+* [DaemonSet Metrics](metrics/workload/daemonset-metrics.md)
+* [Deployment Metrics](metrics/workload/deployment-metrics.md)
+* [Endpoint Metrics](metrics/service/endpoint-metrics.md)
+* [Horizontal Pod Autoscaler Metrics](metrics/workload/horizontalpodautoscaler-metrics.md)
+* [Ingress Metrics](metrics/service/ingress-metrics.md)
+* [Job Metrics](metrics/workload/job-metrics.md)
+* [Lease Metrics](metrics/cluster/lease-metrics.md)
+* [LimitRange Metrics](metrics/policy/limitrange-metrics.md)
+* [MutatingWebhookConfiguration Metrics](metrics/extend/mutatingwebhookconfiguration-metrics.md)
+* [Namespace Metrics](metrics/cluster/namespace-metrics.md)
+* [NetworkPolicy Metrics](metrics/policy/networkpolicy-metrics.md)
+* [Node Metrics](metrics/cluster/node-metrics.md)
+* [PersistentVolume Metrics](metrics/storage/persistentvolume-metrics.md)
+* [PersistentVolumeClaim Metrics](metrics/storage/persistentvolumeclaim-metrics.md)
+* [Pod Disruption Budget Metrics](metrics/policy/poddisruptionbudget-metrics.md)
+* [Pod Metrics](metrics/workload/pod-metrics.md)
+* [ReplicaSet Metrics](metrics/workload/replicaset-metrics.md)
+* [ReplicationController Metrics](metrics/workload/replicationcontroller-metrics.md)
+* [ResourceQuota Metrics](metrics/policy/resourcequota-metrics.md)
+* [Secret Metrics](metrics/storage/secret-metrics.md)
+* [Service Metrics](metrics/service/service-metrics.md)
+* [StatefulSet Metrics](metrics/workload/statefulset-metrics.md)
+* [StorageClass Metrics](metrics/storage/storageclass-metrics.md)
+* [ValidatingWebhookConfiguration Metrics](metrics/extend/validatingwebhookconfiguration-metrics.md)
+* [VolumeAttachment Metrics](metrics/storage/volumeattachment-metrics.md)
 
 ### Optional Resources
 
-* [ClusterRole Metrics](clusterrole-metrics.md)
-* [ClusterRoleBinding Metrics](clusterrolebinding-metrics.md)
-* [EndpointSlice Metrics](endpointslice-metrics.md)
-* [IngressClass Metrics](ingressclass-metrics.md)
-* [Role Metrics](role-metrics.md)
-* [RoleBinding Metrics](rolebinding-metrics.md)
-* [ServiceAccount Metrics](serviceaccount-metrics.md)
+* [ClusterRole Metrics](metrics/cluster/clusterrole-metrics.md)
+* [ClusterRoleBinding Metrics](metrics/cluster/clusterrolebinding-metrics.md)
+* [EndpointSlice Metrics](metrics/service/endpointslice-metrics.md)
+* [IngressClass Metrics](metrics/service/ingressclass-metrics.md)
+* [Role Metrics](metrics/auth/role-metrics.md)
+* [RoleBinding Metrics](metrics/auth/rolebinding-metrics.md)
+* [ServiceAccount Metrics](metrics/auth/serviceaccount-metrics.md)
 
 ## Join Metrics
 
@@ -92,8 +92,8 @@ sum(kube_pod_container_resource_requests{resource="memory"}) by (namespace, pod,
 
 ## Metrics from Custom Resources
 
-See [Custom Resource State Metrics](customresourcestate-metrics.md) for experimental support for custom resources.
+See [Custom Resource State Metrics](metrics/extend/customresourcestate-metrics.md) for experimental support for custom resources.
 
 ## CLI Arguments
 
-Additionally, options for `kube-state-metrics` can be passed when executing as a CLI, or in a kubernetes / openshift environment. More information can be found here: [CLI Arguments](cli-arguments.md)
+Additionally, options for `kube-state-metrics` can be passed when executing as a CLI, or in a kubernetes / openshift environment. More information can be found here: [CLI Arguments](developer/cli-arguments.md)

docs/cli-arguments.md → docs/developer/cli-arguments.md

@@ -23,7 +23,7 @@ spec:
 
 <!-- markdownlint-disable blanks-around-fences -->
 <!-- markdownlint-disable link-image-reference-definitions -->
-[embedmd]:# (../help.txt)
+[embedmd]:# (../../help.txt)
 ```txt
 $ kube-state-metrics -h
 kube-state-metrics is a simple service that listens to the Kubernetes API server and generates metrics about the state of the objects.

docs/developer/guide.md

@@ -12,15 +12,15 @@ Any contribution to improving this documentation will be appreciated.
 
 The following steps are needed to introduce a new resource and its respective resource metrics.
 
-* Reference your new resource(s) to the [docs/README.md](https://github.com/kubernetes/kube-state-metrics/blob/main/docs/README.md#exposed-metrics).
-* Reference your new resource(s) in the [docs/cli-arguments.md](https://github.com/kubernetes/kube-state-metrics/blob/main/docs/cli-arguments.md#available-options) as part of the `--resources` flag.
-* Create a new `<name-of-resource>.md` in the [docs](https://github.com/kubernetes/kube-state-metrics/tree/main/docs) directory to provide documentation on the resource(s) and metrics you implemented. Follow the formatting of all other resources.
-* Add the resource(s) you are representing to the [jsonnet/kube-state-metrics/kube-state-metrics.libsonnet](https://github.com/kubernetes/kube-state-metrics/blob/main/jsonnet/kube-state-metrics/kube-state-metrics.libsonnet) under the appropriate `apiGroup` using the `verbs`: `list` and `watch`.
-* Run `make examples/standard`, this should re-generate [examples/standard/cluster-role.yaml](https://github.com/kubernetes/kube-state-metrics/blob/main/examples/standard/cluster-role.yaml) with the resource(s) added to [jsonnet/kube-state-metrics/kube-state-metrics.libsonnet](https://github.com/kubernetes/kube-state-metrics/blob/main/jsonnet/kube-state-metrics/kube-state-metrics.libsonnet).
-* Reference and add build functions for the new resource(s) in [internal/store/builder.go](https://github.com/kubernetes/kube-state-metrics/blob/main/internal/store/builder.go).
-* Reference the new resource in [pkg/options/resource.go](https://github.com/kubernetes/kube-state-metrics/blob/main/pkg/options/resource.go).
-* Add a sample Kubernetes manifest to be used by tests in the [tests/manifests/](https://github.com/kubernetes/kube-state-metrics/tree/main/tests/manifests) directory.
-* Lastly, and most importantly, actually implement your new resource(s) and its test binary in [internal/store](https://github.com/kubernetes/kube-state-metrics/tree/main/internal/store). Follow the formatting and structure of other resources.
+* Reference your new resource(s) to the [docs/README.md](./../README.md#exposed-metrics).
+* Reference your new resource(s) in the [docs/developer/cli-arguments.md](./cli-arguments.md#available-options) as part of the `--resources` flag.
+* Create a new `<name-of-resource>.md` in the [docs](./../docs) directory to provide documentation on the resource(s) and metrics you implemented. Follow the formatting of all other resources.
+* Add the resource(s) you are representing to the [jsonnet/kube-state-metrics/kube-state-metrics.libsonnet](./../../jsonnet/kube-state-metrics/kube-state-metrics.libsonnet) under the appropriate `apiGroup` using the `verbs`: `list` and `watch`.
+* Run `make examples/standard`, this should re-generate [examples/standard/cluster-role.yaml](./../../examples/standard/cluster-role.yaml) with the resource(s) added to [jsonnet/kube-state-metrics/kube-state-metrics.libsonnet](./../../jsonnet/kube-state-metrics/kube-state-metrics.libsonnet).
+* Reference and add build functions for the new resource(s) in [internal/store/builder.go](./../../internal/store/builder.go).
+* Reference the new resource in [pkg/options/resource.go](./../../pkg/options/resource.go).
+* Add a sample Kubernetes manifest to be used by tests in the [tests/manifests/](./../../tests/manifests) directory.
+* Lastly, and most importantly, actually implement your new resource(s) and its test binary in [internal/store](./../../internal/store). Follow the formatting and structure of other resources.
 
 ### Add New Metrics
 

docs/certificatesigningrequest-metrics.md → docs/metrics/auth/certificatesigningrequest-metrics.md

@@ -2,8 +2,8 @@
 
 | Metric name                                | Metric type | Description                                                                                                               | Labels/tags                                                                                                                                                                   | Status       |
 | ------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
-| kube_certificatesigningrequest_annotations | Gauge       | Kubernetes annotations converted to Prometheus labels controlled via [--metric-annotations-allowlist](./cli-arguments.md) | `certificatesigningrequest`=&lt;certificatesigningrequest-name&gt; <br> `signer_name`=&lt;certificatesigningrequest-signer-name&gt;                                           | EXPERIMENTAL |
+| kube_certificatesigningrequest_annotations | Gauge       | Kubernetes annotations converted to Prometheus labels controlled via [--metric-annotations-allowlist](../../developer/cli-arguments.md) | `certificatesigningrequest`=&lt;certificatesigningrequest-name&gt; <br> `signer_name`=&lt;certificatesigningrequest-signer-name&gt;                                           | EXPERIMENTAL |
 | kube_certificatesigningrequest_created     | Gauge       |                                                                                                                           | `certificatesigningrequest`=&lt;certificatesigningrequest-name&gt; <br> `signer_name`=&lt;certificatesigningrequest-signer-name&gt;                                           | STABLE       |
 | kube_certificatesigningrequest_condition   | Gauge       |                                                                                                                           | `certificatesigningrequest`=&lt;certificatesigningrequest-name&gt; <br> `signer_name`=&lt;certificatesigningrequest-signer-name&gt; <br> `condition`=&lt;approved\|denied&gt; | STABLE       |
-| kube_certificatesigningrequest_labels      | Gauge       | Kubernetes labels converted to Prometheus labels controlled via [--metric-labels-allowlist](./cli-arguments.md)           | `certificatesigningrequest`=&lt;certificatesigningrequest-name&gt; <br> `signer_name`=&lt;certificatesigningrequest-signer-name&gt;                                           | STABLE       |
+| kube_certificatesigningrequest_labels      | Gauge       | Kubernetes labels converted to Prometheus labels controlled via [--metric-labels-allowlist](../../developer/cli-arguments.md)           | `certificatesigningrequest`=&lt;certificatesigningrequest-name&gt; <br> `signer_name`=&lt;certificatesigningrequest-signer-name&gt;                                           | STABLE       |
 | kube_certificatesigningrequest_cert_length | Gauge       |                                                                                                                           | `certificatesigningrequest`=&lt;certificatesigningrequest-name&gt; <br> `signer_name`=&lt;certificatesigningrequest-signer-name&gt;                                           | STABLE       |

docs/role-metrics.md → docs/metrics/auth/role-metrics.md

@@ -2,8 +2,8 @@
 
 | Metric name                         | Metric type | Description                                                                                                               | Labels/tags                                                      | Status       |
 | ----------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------ |
-| kube_role_annotations               | Gauge       | Kubernetes annotations converted to Prometheus labels controlled via [--metric-annotations-allowlist](./cli-arguments.md) | `role`=&lt;role-name&gt; <br> `namespace`=&lt;role-namespace&gt; | EXPERIMENTAL |
-| kube_role_labels                    | Gauge       | Kubernetes labels converted to Prometheus labels controlled via [--metric-labels-allowlist](./cli-arguments.md)           | `role`=&lt;role-name&gt; <br> `namespace`=&lt;role-namespace&gt; | EXPERIMENTAL |
+| kube_role_annotations               | Gauge       | Kubernetes annotations converted to Prometheus labels controlled via [--metric-annotations-allowlist](../../developer/cli-arguments.md) | `role`=&lt;role-name&gt; <br> `namespace`=&lt;role-namespace&gt; | EXPERIMENTAL |
+| kube_role_labels                    | Gauge       | Kubernetes labels converted to Prometheus labels controlled via [--metric-labels-allowlist](../../developer/cli-arguments.md)           | `role`=&lt;role-name&gt; <br> `namespace`=&lt;role-namespace&gt; | EXPERIMENTAL |
 | kube_role_info                      | Gauge       |                                                                                                                           | `role`=&lt;role-name&gt; <br> `namespace`=&lt;role-namespace&gt; | EXPERIMENTAL |
 | kube_role_created                   | Gauge       |                                                                                                                           | `role`=&lt;role-name&gt; <br> `namespace`=&lt;role-namespace&gt; | EXPERIMENTAL |
 | kube_role_metadata_resource_version | Gauge       |                                                                                                                           | `role`=&lt;role-name&gt; <br> `namespace`=&lt;role-namespace&gt; | EXPERIMENTAL |