Improvements for automated documentation

.drone.star

@@ -33,7 +33,7 @@ def testing(ctx):
     'steps': [
       {
         'name': 'generate',
-        'image': 'webhippie/golang:1.15',
+        'image': 'webhippie/golang:1.16',
         'pull': 'always',
         'commands': [
           'make generate',
@@ -47,7 +47,7 @@ def testing(ctx):
       },
       {
         'name': 'vet',
-        'image': 'webhippie/golang:1.15',
+        'image': 'webhippie/golang:1.16',
         'pull': 'always',
         'commands': [
           'make vet',
@@ -61,7 +61,7 @@ def testing(ctx):
       },
       {
         'name': 'staticcheck',
-        'image': 'webhippie/golang:1.15',
+        'image': 'webhippie/golang:1.16',
         'pull': 'always',
         'commands': [
           'make staticcheck',
@@ -75,7 +75,7 @@ def testing(ctx):
       },
       {
         'name': 'lint',
-        'image': 'webhippie/golang:1.15',
+        'image': 'webhippie/golang:1.16',
         'pull': 'always',
         'commands': [
           'make lint',
@@ -89,7 +89,7 @@ def testing(ctx):
       },
       {
         'name': 'build',
-        'image': 'webhippie/golang:1.15',
+        'image': 'webhippie/golang:1.16',
         'pull': 'always',
         'commands': [
           'make build',
@@ -103,7 +103,7 @@ def testing(ctx):
       },
       {
         'name': 'test',
-        'image': 'webhippie/golang:1.15',
+        'image': 'webhippie/golang:1.16',
         'pull': 'always',
         'commands': [
           'make test',
@@ -179,7 +179,7 @@ def docker(ctx, arch):
       'dry_run': True,
       'tags': 'linux-%s' % (arch),
       'dockerfile': 'docker/Dockerfile.linux.%s' % (arch),
-      'repo': ctx.repo.slug,
+      'repo': ctx.repo.slug.replace('_', '-'),
     }
   else:
     docker = {
@@ -192,7 +192,7 @@ def docker(ctx, arch):
       'auto_tag': True,
       'auto_tag_suffix': 'linux-%s' % (arch),
       'dockerfile': 'docker/Dockerfile.linux.%s' % (arch),
-      'repo': ctx.repo.slug,
+      'repo': ctx.repo.slug.replace('_', '-'),
     }
 
   return {
@@ -204,24 +204,9 @@ def docker(ctx, arch):
       'arch': agent,
     },
     'steps': [
-      {
-        'name': 'version',
-        'image': 'webhippie/golang:1.15',
-        'pull': 'always',
-        'environment': environment,
-        'commands': [
-          'go env',
-        ],
-        'volumes': [
-          {
-            'name': 'gopath',
-            'path': '/srv/app',
-          },
-        ],
-      },
       {
         'name': 'generate',
-        'image': 'webhippie/golang:1.15',
+        'image': 'webhippie/golang:1.16',
         'pull': 'always',
         'environment': environment,
         'commands': [
@@ -236,7 +221,7 @@ def docker(ctx, arch):
       },
       {
         'name': 'build',
-        'image': 'webhippie/golang:1.15',
+        'image': 'webhippie/golang:1.16',
         'pull': 'always',
         'environment': environment,
         'commands': [
@@ -286,7 +271,7 @@ def binary(ctx, name):
     'steps': [
       {
         'name': 'generate',
-        'image': 'webhippie/golang:1.15',
+        'image': 'webhippie/golang:1.16',
         'pull': 'always',
         'commands': [
           'make generate',
@@ -300,7 +285,7 @@ def binary(ctx, name):
       },
       {
         'name': 'build',
-        'image': 'webhippie/golang:1.15',
+        'image': 'webhippie/golang:1.16',
         'pull': 'always',
         'commands': [
           'make release-%s' % (name),
@@ -314,7 +299,7 @@ def binary(ctx, name):
       },
       {
         'name': 'finish',
-        'image': 'webhippie/golang:1.15',
+        'image': 'webhippie/golang:1.16',
         'pull': 'always',
         'commands': [
           'make release-finish',
@@ -459,6 +444,22 @@ def docs(ctx):
       'arch': 'amd64',
     },
     'steps': [
+      {
+        'name': 'envvars',
+        'image': 'webhippie/golang:1.16',
+        'pull': 'always',
+        'commands': [
+          'make envvars',
+        ],
+      },
+      {
+        'name': 'labels',
+        'image': 'webhippie/golang:1.16',
+        'pull': 'always',
+        'commands': [
+          'make labels',
+        ],
+      },
       {
         'name': 'generate',
         'image': 'webhippie/hugo:latest',
@@ -534,17 +535,33 @@ def changelog(ctx):
           },
         },
       },
+      {
+        'name': 'envvars',
+        'image': 'webhippie/golang:1.16',
+        'pull': 'always',
+        'commands': [
+          'make envvars',
+        ],
+      },
+      {
+        'name': 'labels',
+        'image': 'webhippie/golang:1.16',
+        'pull': 'always',
+        'commands': [
+          'make labels',
+        ],
+      },
       {
         'name': 'generate',
-        'image': 'webhippie/golang:1.15',
+        'image': 'webhippie/golang:1.16',
         'pull': 'always',
         'commands': [
           'make changelog',
         ],
       },
       {
         'name': 'changes',
-        'image': 'webhippie/golang:1.15',
+        'image': 'webhippie/golang:1.16',
         'pull': 'always',
         'commands': [
           'git diff CHANGELOG.md',
@@ -559,7 +576,7 @@ def changelog(ctx):
             'commit',
             'push',
           ],
-          'message': 'Automated changelog update [skip ci]',
+          'message': 'Automated changelog and docs update [skip ci]',
           'branch': 'master',
           'author_email': '[email protected]',
           'author_name': 'Drone',
@@ -612,7 +629,7 @@ def readme(ctx):
             'from_secret': 'docker_password',
           },
           'DOCKERHUB_REPO_PREFIX': ctx.repo.namespace,
-          'DOCKERHUB_REPO_NAME': ctx.repo.name,
+          'DOCKERHUB_REPO_NAME': ctx.repo.name.replace('_', '-'),
           'SHORT_DESCRIPTION': description,
           'README_PATH': 'README.md',
         },

Makefile

@@ -183,6 +183,14 @@ release-finish: release-reduce release-checksum
 docs:
 	hugo -s docs/
 
+.PHONY: envvars
+envvars:
+	go run hack/generate-envvars-docs.go
+
+.PHONY: labels
+labels:
+	go run hack/generate-labels-docs.go
+
 .PHONY: watch
 watch:
 	$(REFLEX) -c reflex.conf

changelog/unreleased/dep-and-go-update.md

@@ -4,4 +4,4 @@ We updated the Go version used to build the binaries within the CI system and
 beside that in the same step we have updated all dependencies ti keep everything
 up to date.
 
-https://github.com/promhippie/prometheus-hcloud-sd/issues/20
+https://github.com/promhippie/prometheus-hcloud-sd/pull/44

changelog/unreleased/docs-improvements.md

@@ -0,0 +1,8 @@
+Change: Improvements for automated documentation
+
+We have added some simple scripts that gets executed by Drone to keep moving
+documentation parts like the available labels or the available environment
+variables always up to date. No need to update the docs related to that manually
+anymore.
+
+https://github.com/promhippie/prometheus-hcloud-sd/pull/44

docs/.gitignore

@@ -0,0 +1,2 @@
+public/
+resources/

docs/content/getting-started.md

@@ -95,100 +95,30 @@ Depending on how you have launched and configured [Prometheus](https://prometheu
       - ./service-discovery:/etc/sd
 {{< / highlight >}}
 
-Finally the service discovery should be configured fine, let's start this stack with [docker-compose](https://docs.docker.com/compose/), you just need to execute `docker-compose up` within the directory where you have stored `prometheus.yml` and `docker-compose.yml`.
-
-{{< highlight txt >}}
-# docker-compose up
-Creating network "hcloud-sd_default" with the default driver
-Creating volume "hcloud-sd_prometheus" with default driver
-Creating hcloud-sd_hcloud-sd_1  ... done
-Creating hcloud-sd_prometheus_1 ... done
-Attaching to hcloud-sd_hcloud-sd_1, hcloud-sd_prometheus_1
-prometheus_1  | level=info ts=2018-10-07T15:49:32.5574151Z caller=main.go:238 msg="Starting Prometheus" version="(version=2.4.3, branch=HEAD, revision=167a4b4e73a8eca8df648d2d2043e21bdb9a7449)"
-prometheus_1  | level=info ts=2018-10-07T15:49:32.5574847Z caller=main.go:239 build_context="(go=go1.11.1, user=root@1e42b46043e9, date=20181004-08:42:02)"
-prometheus_1  | level=info ts=2018-10-07T15:49:32.5575116Z caller=main.go:240 host_details="(Linux 4.9.93-linuxkit-aufs #1 SMP Wed Jun 6 16:55:56 UTC 2018 x86_64 14ae580d073a (none))"
-prometheus_1  | level=info ts=2018-10-07T15:49:32.5575347Z caller=main.go:241 fd_limits="(soft=1048576, hard=1048576)"
-prometheus_1  | level=info ts=2018-10-07T15:49:32.5575521Z caller=main.go:242 vm_limits="(soft=unlimited, hard=unlimited)"
-prometheus_1  | level=info ts=2018-10-07T15:49:32.5588845Z caller=main.go:554 msg="Starting TSDB ..."
-prometheus_1  | level=info ts=2018-10-07T15:49:32.5590007Z caller=web.go:397 component=web msg="Start listening for connections" address=0.0.0.0:9090
-prometheus_1  | level=info ts=2018-10-07T15:49:32.5639949Z caller=main.go:564 msg="TSDB started"
-prometheus_1  | level=info ts=2018-10-07T15:49:32.5640454Z caller=main.go:624 msg="Loading configuration file" filename=/etc/prometheus/prometheus.yml
-prometheus_1  | level=info ts=2018-10-07T15:49:32.5674651Z caller=main.go:650 msg="Completed loading of configuration file" filename=/etc/prometheus/prometheus.yml
-prometheus_1  | level=info ts=2018-10-07T15:49:32.5675144Z caller=main.go:523 msg="Server is ready to receive web requests."
-hcloud-sd_1   | level=info ts=2018-10-07T15:49:32.5843003Z msg="Launching Prometheus HetznerCloud SD" version=0.0.0-master revision=00c6143 date=20180924 go=go1.11
-hcloud-sd_1   | level=info ts=2018-10-07T15:49:32.5845589Z msg="Starting metrics server" addr=0.0.0.0:9000
-{{< / highlight >}}
-
-That's all, the service discovery should be up and running. You can access [Prometheus](https://prometheus.io) at [http://localhost:9090](http://localhost:9090).
+Finally the service discovery should be configured fine, let's start this stack with [docker-compose](https://docs.docker.com/compose/), you just need to execute `docker-compose up` within the directory where you have stored `prometheus.yml` and `docker-compose.yml`. That's all, the service discovery should be up and running. You can access [Prometheus](https://prometheus.io) at [http://localhost:9090](http://localhost:9090).
 
 {{< figure src="service-discovery.png" title="Prometheus service discovery for HetznerCloud" >}}
 
-## Kubernetes
-
-Currently we have not prepared a deployment for Kubernetes, but this is something we will provide for sure. Most interesting will be the integration into the [Prometheus Operator](https://coreos.com/operators/prometheus/docs/latest/), so stay tuned.
-
 ## Configuration
 
 ### Envrionment variables
 
 If you prefer to configure the service with environment variables you can see the available variables below, in case you want to configure multiple accounts with a single service you are forced to use the configuration file as the environment variables are limited to a single account. As the service is pretty lightweight you can even start an instance per account and configure it entirely by the variables, it's up to you.
 
-PROMETHEUS_HCLOUD_CONFIG
-: Path to HetznerCloud configuration file, optionally, required for multi credentials
-
-PROMETHEUS_HCLOUD_TOKEN
-: Access token for the HetznerCloud API, required for authentication
-
-PROMETHEUS_HCLOUD_LOG_LEVEL
-: Only log messages with given severity, defaults to `info`
-
-PROMETHEUS_HCLOUD_LOG_PRETTY
-: Enable pretty messages for logging, defaults to `true`
-
-PROMETHEUS_HCLOUD_WEB_ADDRESS
-: Address to bind the metrics server, defaults to `0.0.0.0:9000`
-
-PROMETHEUS_HCLOUD_WEB_PATH
-: Path to bind the metrics server, defaults to `/metrics`
-
-PROMETHEUS_HCLOUD_OUTPUT_FILE
-: Path to write the file_sd config, defaults to `/etc/prometheus/hcloud.json`
-
-PROMETHEUS_HCLOUD_OUTPUT_REFRESH
-: Discovery refresh interval in seconds, defaults to `30`
+{{< partial "envvars.md" >}}
 
 ### Configuration file
 
 Especially if you want to configure multiple accounts within a single service discovery you got to use the configuration file. So far we support the file formats `JSON` and `YAML`, if you want to get a full example configuration just take a look at [our repository](https://github.com/promhippie/prometheus-hcloud-sd/tree/master/config), there you can always see the latest configuration format. These example configurations include all available options, they also include the default values.
 
 ## Labels
 
-* `__address__`
-* `__meta_hcloud_city`
-* `__meta_hcloud_cores`
-* `__meta_hcloud_country`
-* `__meta_hcloud_cpu`
-* `__meta_hcloud_datacenter`
-* `__meta_hcloud_disk`
-* `__meta_hcloud_image_name`
-* `__meta_hcloud_image_type`
-* `__meta_hcloud_label_<label>`
-* `__meta_hcloud_location`
-* `__meta_hcloud_memory`
-* `__meta_hcloud_name`
-* `__meta_hcloud_os_flavor`
-* `__meta_hcloud_os_version`
-* `__meta_hcloud_project`
-* `__meta_hcloud_public_ipv4`
-* `__meta_hcloud_public_ipv6`
-* `__meta_hcloud_status`
-* `__meta_hcloud_storage`
-* `__meta_hcloud_type`
+{{< partial "labels.md" >}}
 
 ## Metrics
 
-prometheus_hcloud_sd_request_duration_seconds
+prometheus_hcloud_sd_request_duration_seconds{project}
 : Histogram of latencies for requests to the HetznerCloud API
 
-prometheus_hcloud_sd_request_failures_total
+prometheus_hcloud_sd_request_failures_total{project}
 : Total number of failed requests to the HetznerCloud API

docs/layouts/shortcodes/partial.html

@@ -0,0 +1 @@
+{{- $file := printf "/partials/%s" (.Get 0) -}}{{- $file | readFile | markdownify -}}

docs/partials/envvars.md

@@ -0,0 +1,23 @@
+PROMETHEUS_HCLOUD_LOG_LEVEL
+: Only log messages with given severity, defaults to `info`
+
+PROMETHEUS_HCLOUD_LOG_PRETTY
+: Enable pretty messages for logging, defaults to `false`
+
+PROMETHEUS_HCLOUD_WEB_ADDRESS
+: Address to bind the metrics server, defaults to `0.0.0.0:9000`
+
+PROMETHEUS_HCLOUD_WEB_PATH
+: Path to bind the metrics server, defaults to `/metrics`
+
+PROMETHEUS_HCLOUD_OUTPUT_FILE
+: Path to write the file_sd config, defaults to `/etc/prometheus/hcloud.json`
+
+PROMETHEUS_HCLOUD_OUTPUT_REFRESH
+: Discovery refresh interval in seconds, defaults to `30`
+
+PROMETHEUS_HCLOUD_TOKEN
+: Access token for the HetznerCloud API
+
+PROMETHEUS_HCLOUD_CONFIG
+: Path to HetznerCloud configuration file

docs/partials/labels.md

@@ -0,0 +1,21 @@
+* `__address__`
+* `__meta_hcloud_city`
+* `__meta_hcloud_cores`
+* `__meta_hcloud_country`
+* `__meta_hcloud_cpu`
+* `__meta_hcloud_datacenter`
+* `__meta_hcloud_disk`
+* `__meta_hcloud_image_name`
+* `__meta_hcloud_image_type`
+* `__meta_hcloud_label_<name>`
+* `__meta_hcloud_location`
+* `__meta_hcloud_memory`
+* `__meta_hcloud_name`
+* `__meta_hcloud_os_flavor`
+* `__meta_hcloud_os_version`
+* `__meta_hcloud_project`
+* `__meta_hcloud_public_ipv4`
+* `__meta_hcloud_public_ipv6`
+* `__meta_hcloud_status`
+* `__meta_hcloud_storage`
+* `__meta_hcloud_type`