Setup mdox

Signed-off-by: Saswata Mukherjee <[email protected]>

Author: saswatamcode

.github/workflows/ci.yaml

@@ -22,6 +22,17 @@ jobs:
       with:
         go-version: ${{ env.golang-version }}
     - run: make --always-make generate validate && git diff --exit-code
+  check-docs:
+    runs-on: ubuntu-latest
+    name: Check Documentation formatting and links
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        persist-credentials: false
+    - uses: actions/setup-go@v2
+      with:
+        go-version: ${{ env.golang-version }}
+    - run: make check-docs
   lint:
     runs-on: ubuntu-latest
     name: Jsonnet linter

.mdox.validate.yaml

@@ -0,0 +1,9 @@
+version: 1
+
+validators:
+  # Ignore localhost links.
+  - regex: 'localhost'
+    type: "ignore"
+  # Ignore release links.
+  - regex: 'https:\/\/github\.com\/prometheus-operator\/kube-prometheus\/releases'
+    type: "ignore"

Makefile

@@ -2,29 +2,39 @@ SHELL=/bin/bash -o pipefail
 
 BIN_DIR?=$(shell pwd)/tmp/bin
 
-EMBEDMD_BIN=$(BIN_DIR)/embedmd
+MDOX_BIN=$(BIN_DIR)/mdox
 JB_BIN=$(BIN_DIR)/jb
 GOJSONTOYAML_BIN=$(BIN_DIR)/gojsontoyaml
 JSONNET_BIN=$(BIN_DIR)/jsonnet
 JSONNETLINT_BIN=$(BIN_DIR)/jsonnet-lint
 JSONNETFMT_BIN=$(BIN_DIR)/jsonnetfmt
 KUBECONFORM_BIN=$(BIN_DIR)/kubeconform
-TOOLING=$(EMBEDMD_BIN) $(JB_BIN) $(GOJSONTOYAML_BIN) $(JSONNET_BIN) $(JSONNETLINT_BIN) $(JSONNETFMT_BIN) $(KUBECONFORM_BIN)
+TOOLING=$(JB_BIN) $(GOJSONTOYAML_BIN) $(JSONNET_BIN) $(JSONNETLINT_BIN) $(JSONNETFMT_BIN) $(KUBECONFORM_BIN) $(MDOX_BIN)
 
 JSONNETFMT_ARGS=-n 2 --max-blank-lines 2 --string-style s --comment-style s
 
-all: generate fmt test
+MDOX_VALIDATE_CONFIG?=.mdox.validate.yaml
+MD_FILES_TO_FORMAT=$(shell find docs developer-workspace examples experimental jsonnet manifests -name "*.md") $(shell ls *.md)
+
+all: generate fmt test docs
 
 .PHONY: clean
 clean:
 	# Remove all files and directories ignored by git.
 	git clean -Xfd .
 
-.PHONY: generate
-generate: manifests **.md
+.PHONY: docs
+docs: $(MDOX_BIN) $(shell find examples) build.sh example.jsonnet
+	@echo ">> formatting and local/remote links"
+	$(MDOX_BIN) fmt --soft-wraps -l --links.localize.address-regex="https://prometheus-operator.dev/.*" --links.validate.config-file=$(MDOX_VALIDATE_CONFIG) $(MD_FILES_TO_FORMAT)
 
-**.md: $(EMBEDMD_BIN) $(shell find examples) build.sh example.jsonnet
-	$(EMBEDMD_BIN) -w `find . -name "*.md" | grep -v vendor`
+.PHONY: check-docs
+check-docs: $(MDOX_BIN) $(shell find examples) build.sh example.jsonnet
+	@echo ">> checking formatting and local/remote links"
+	$(MDOX_BIN) fmt --soft-wraps --check -l --links.localize.address-regex="https://prometheus-operator.dev/.*" --links.validate.config-file=$(MDOX_VALIDATE_CONFIG) $(MD_FILES_TO_FORMAT)
+
+.PHONY: generate
+generate: manifests
 
 manifests: examples/kustomize.jsonnet $(GOJSONTOYAML_BIN) vendor
 	./build.sh $<

README.md

@@ -173,7 +173,7 @@ Then access via [http://localhost:9093](http://localhost:9093)
 ## Customizing Kube-Prometheus
 
 This section:
- * describes how to customize the kube-prometheus library via compiling the kube-prometheus manifests yourself (as an alternative to the [Quickstart section](#Quickstart)).
+ * describes how to customize the kube-prometheus library via compiling the kube-prometheus manifests yourself (as an alternative to the [Quickstart section](#quickstart)).
  * still doesn't require you to make a copy of this entire repository, but rather only a copy of a few select files.
 
 ### Installing
@@ -210,8 +210,7 @@ Here's [example.jsonnet](example.jsonnet):
 
 > Note: some of the following components must be configured beforehand. See [configuration](#configuration) and [customization-examples](#customization-examples).
 
-[embedmd]:# (example.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat example.jsonnet"
 local kp =
   (import 'kube-prometheus/main.libsonnet') +
   // Uncomment the following imports to enable its patches
@@ -250,8 +249,7 @@ local kp =
 
 And here's the [build.sh](build.sh) script (which uses `vendor/` to render all manifests in a json structure of `{filename: manifest-content}`):
 
-[embedmd]:# (build.sh)
-```sh
+```sh mdox-exec="cat build.sh"
 #!/usr/bin/env bash
 
 # This script uses arg $1 (name of *.jsonnet file to use) to generate the manifests/*.yaml files.
@@ -343,7 +341,7 @@ Configuration is mainly done in the `values` map. You can see this being used in
     },
 ```
 
-The grafana definition is located in a different project (https://github.com/brancz/kubernetes-grafana), but needed configuration can be customized from the same top level `values` field. For example to allow anonymous access to grafana, add the following `values` section:
+The grafana definition is located in a different project (https://github.com/brancz/kubernetes-grafana ), but needed configuration can be customized from the same top level `values` field. For example to allow anonymous access to grafana, add the following `values` section:
 ```
       grafana+:: {
         config: { // http://docs.grafana.org/installation/configuration/
@@ -373,8 +371,7 @@ A common example is that not all Kubernetes clusters are created exactly the sam
 
 These mixins are selectable via the `platform` field of kubePrometheus:
 
-[embedmd]:# (examples/jsonnet-snippets/platform.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/jsonnet-snippets/platform.jsonnet"
 (import 'kube-prometheus/main.libsonnet') +
 {
   values+:: {
@@ -406,8 +403,7 @@ The output of this command can be piped to a shell to be executed by appending `
 
 Then to generate manifests with `internal-registry.com/organization`, use the `withImageRepository` mixin:
 
-[embedmd]:# (examples/internal-registry.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/internal-registry.jsonnet"
 local mixin = import 'kube-prometheus/addons/config-mixins.libsonnet';
 local kp = (import 'kube-prometheus/main.libsonnet') + {
   values+:: {
@@ -430,8 +426,7 @@ local kp = (import 'kube-prometheus/main.libsonnet') + {
 
 Another mixin that may be useful for exploring the stack is to expose the UIs of Prometheus, Alertmanager and Grafana on NodePorts:
 
-[embedmd]:# (examples/jsonnet-snippets/node-ports.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/jsonnet-snippets/node-ports.jsonnet"
 (import 'kube-prometheus/main.libsonnet') +
 (import 'kube-prometheus/addons/node-ports.libsonnet')
 ```
@@ -440,8 +435,7 @@ Another mixin that may be useful for exploring the stack is to expose the UIs of
 
 To give another customization example, the name of the `Prometheus` object provided by this library can be overridden:
 
-[embedmd]:# (examples/prometheus-name-override.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/prometheus-name-override.jsonnet"
 ((import 'kube-prometheus/main.libsonnet') + {
    prometheus+: {
      prometheus+: {
@@ -457,8 +451,7 @@ To give another customization example, the name of the `Prometheus` object provi
 
 Standard Kubernetes manifests are all written using [ksonnet-lib](https://github.com/ksonnet/ksonnet-lib/), so they can be modified with the mixins supplied by ksonnet-lib. For example to override the namespace of the node-exporter DaemonSet:
 
-[embedmd]:# (examples/ksonnet-example.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/ksonnet-example.jsonnet"
 ((import 'kube-prometheus/main.libsonnet') + {
    nodeExporter+: {
      daemonset+: {
@@ -474,8 +467,7 @@ Standard Kubernetes manifests are all written using [ksonnet-lib](https://github
 
 The Alertmanager configuration is located in the `values.alertmanager.config` configuration field. In order to set a custom Alertmanager configuration simply set this field.
 
-[embedmd]:# (examples/alertmanager-config.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/alertmanager-config.jsonnet"
 ((import 'kube-prometheus/main.libsonnet') + {
    values+:: {
      alertmanager+: {
@@ -502,8 +494,7 @@ The Alertmanager configuration is located in the `values.alertmanager.config` co
 
 In the above example the configuration has been inlined, but can just as well be an external file imported in jsonnet via the `importstr` function.
 
-[embedmd]:# (examples/alertmanager-config-external.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/alertmanager-config-external.jsonnet"
 ((import 'kube-prometheus/main.libsonnet') + {
    values+:: {
      alertmanager+: {
@@ -517,8 +508,7 @@ In the above example the configuration has been inlined, but can just as well be
 
 In order to monitor additional namespaces, the Prometheus server requires the appropriate `Role` and `RoleBinding` to be able to discover targets from that namespace. By default the Prometheus server is limited to the three namespaces it requires: default, kube-system and the namespace you configure the stack to run in via `$.values.namespace`. This is specified in `$.values.prometheus.namespaces`, to add new namespaces to monitor, simply append the additional namespaces:
 
-[embedmd]:# (examples/additional-namespaces.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/additional-namespaces.jsonnet"
 local kp = (import 'kube-prometheus/main.libsonnet') + {
   values+:: {
     common+: {
@@ -548,8 +538,7 @@ In order to Prometheus be able to discovery and scrape services inside the addit
 
 You can define ServiceMonitor resources in your `jsonnet` spec. See the snippet bellow:
 
-[embedmd]:# (examples/additional-namespaces-servicemonitor.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/additional-namespaces-servicemonitor.jsonnet"
 local kp = (import 'kube-prometheus/main.libsonnet') + {
   values+:: {
     common+: {
@@ -601,8 +590,7 @@ local kp = (import 'kube-prometheus/main.libsonnet') + {
 
 In case you want to monitor all namespaces in a cluster, you can add the following mixin. Also, make sure to empty the namespaces defined in prometheus so that roleBindings are not created against them.  
 
-[embedmd]:# (examples/all-namespaces.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/all-namespaces.jsonnet"
 local kp = (import 'kube-prometheus/main.libsonnet') +
            (import 'kube-prometheus/addons/all-namespaces.libsonnet') + {
   values+:: {
@@ -630,7 +618,7 @@ Proceed with [creating ServiceMonitors for the services in the namespaces](#defi
 
 ### Static etcd configuration
 
-In order to configure a static etcd cluster to scrape there is a simple [kube-prometheus-static-etcd.libsonnet](jsonnet/kube-prometheus/kube-prometheus-static-etcd.libsonnet) mixin prepared - see [etcd.jsonnet](examples/etcd.jsonnet) for an example of how to use that mixin, and [Monitoring external etcd](docs/monitoring-external-etcd.md) for more information.
+In order to configure a static etcd cluster to scrape there is a simple [static-etcd.libsonnet](jsonnet/kube-prometheus/addons/static-etcd.libsonnet) mixin prepared - see [etcd.jsonnet](examples/etcd.jsonnet) for an example of how to use that mixin, and [Monitoring external etcd](docs/monitoring-external-etcd.md) for more information.
 
 > Note that monitoring etcd in minikube is currently not possible because of how etcd is setup. (minikube's etcd binds to 127.0.0.1:2379 only, and within host networking namespace.)
 
@@ -639,8 +627,7 @@ In order to configure a static etcd cluster to scrape there is a simple [kube-pr
 To prevent `Prometheus` and `Alertmanager` instances from being deployed onto the same node when
 possible, one can include the [kube-prometheus-anti-affinity.libsonnet](jsonnet/kube-prometheus/addons/anti-affinity.libsonnet) mixin:
 
-[embedmd]:# (examples/anti-affinity.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/anti-affinity.jsonnet"
 local kp = (import 'kube-prometheus/main.libsonnet') +
            (import 'kube-prometheus/addons/anti-affinity.libsonnet') + {
   values+:: {
@@ -664,8 +651,7 @@ local kp = (import 'kube-prometheus/main.libsonnet') +
 Sometimes in small clusters, the CPU/memory limits can get high enough for alerts to be fired continuously. To prevent this, one can strip off the predefined limits.
 To do that, one can import the following mixin
 
-[embedmd]:# (examples/strip-limits.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/strip-limits.jsonnet"
 local kp = (import 'kube-prometheus/main.libsonnet') +
            (import 'kube-prometheus/addons/strip-limits.libsonnet') + {
   values+:: {
@@ -759,7 +745,7 @@ resources. One driver for more resource needs, is a high number of
 namespaces. There may be others.
 
 kube-state-metrics resource allocation is managed by
-[addon-resizer](https://github.com/kubernetes/autoscaler/tree/main/addon-resizer/nanny)
+[addon-resizer](https://github.com/kubernetes/autoscaler/tree/master/addon-resizer/nanny)
 You can control it's parameters by setting variables in the
 config. They default to:
 

developer-workspace/README.md

@@ -26,7 +26,7 @@ If you are working on new features/bug fixes, you can regenerate kube-prometheus
 
 Gitpod is already available to everyone to use for free. It can also run commands that we speficy in the `.gitpod.yml` file located in the root directory of the git repository, so even the cluster creation can be fully automated.
 
-You can use the same workflow as mentioned in the [Codespaces](#Codespaces) section, however Gitpod doesn't have native support for any kubernetes distribution. The workaround is to create a full QEMU Virtual Machine and deploy [k3s](https://github.com/k3s-io/k3s) inside this VM. Don't worry, this whole process is already fully automated, but due to the workaround the whole workspace may be very slow.
+You can use the same workflow as mentioned in the [Codespaces](#codespaces) section, however Gitpod doesn't have native support for any kubernetes distribution. The workaround is to create a full QEMU Virtual Machine and deploy [k3s](https://github.com/k3s-io/k3s) inside this VM. Don't worry, this whole process is already fully automated, but due to the workaround the whole workspace may be very slow.
 
 To open up a workspace with Gitpod, you can install the [Google Chrome extension](https://www.gitpod.io/docs/browser-extension/) to add a new button to Github UI and use it on PRs or from the main page. Or by directly typing in the browser `http://gitpod.io/#https://github.com/prometheus-operator/kube-prometheus/pull/<Pull Request Number>` or just `http://gitpod.io/#https://github.com/prometheus-operator/kube-prometheus`
 

docs/EKS-cni-support.md

@@ -5,8 +5,8 @@ AWS EKS uses [CNI](https://github.com/aws/amazon-vpc-cni-k8s) networking plugin
 One fatal issue that can occur is that you run out of IP addresses in your eks cluster. (Generally happens due to error configs where pods keep scheduling).
 
 You can monitor the `awscni` using kube-promethus with : 
-[embedmd]:# (../examples/eks-cni-example.jsonnet)
-```jsonnet
+
+```jsonnet mdox-exec="cat examples/eks-cni-example.jsonnet"
 local kp = (import 'kube-prometheus/main.libsonnet') + {
   values+:: {
     common+: {

docs/developing-prometheus-rules-and-grafana-dashboards.md

@@ -20,8 +20,7 @@ For both the Prometheus rules and the Grafana dashboards Kubernetes `ConfigMap`s
 
 As a basis, all examples in this guide are based on the base example of the kube-prometheus [readme](../README.md):
 
-[embedmd]:# (../example.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat example.jsonnet"
 local kp =
   (import 'kube-prometheus/main.libsonnet') +
   // Uncomment the following imports to enable its patches
@@ -68,8 +67,7 @@ The format is exactly the Prometheus format, so there should be no changes neces
 
 > Note that alerts can just as well be included into this file, using the jsonnet `import` function. In this example it is just inlined in order to demonstrate their use in a single file.
 
-[embedmd]:# (../examples/prometheus-additional-alert-rule-example.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/prometheus-additional-alert-rule-example.jsonnet"
 local kp = (import 'kube-prometheus/main.libsonnet') + {
   values+:: {
     common+: {
@@ -124,8 +122,7 @@ In order to add a recording rule, simply do the same with the `prometheusRules`
 
 > Note that rules can just as well be included into this file, using the jsonnet `import` function. In this example it is just inlined in order to demonstrate their use in a single file.
 
-[embedmd]:# (../examples/prometheus-additional-recording-rule-example.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/prometheus-additional-recording-rule-example.jsonnet"
 local kp = (import 'kube-prometheus/main.libsonnet') + {
   values+:: {
     common+: {
@@ -184,8 +181,7 @@ cat existingrule.yaml | gojsontoyaml -yamltojson > existingrule.json
 
 Then import it in jsonnet:
 
-[embedmd]:# (../examples/prometheus-additional-rendered-rule-example.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/prometheus-additional-rendered-rule-example.jsonnet"
 local kp = (import 'kube-prometheus/main.libsonnet') + {
   values+:: {
     common+: {
@@ -337,8 +333,7 @@ We recommend using the [grafonnet](https://github.com/grafana/grafonnet-lib/) li
 
 > Note that dashboards can just as well be included into this file, using the jsonnet `import` function. In this example it is just inlined in order to demonstrate their use in a single file.
 
-[embedmd]:# (../examples/grafana-additional-jsonnet-dashboard-example.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/grafana-additional-jsonnet-dashboard-example.jsonnet"
 local grafana = import 'grafonnet/grafana.libsonnet';
 local dashboard = grafana.dashboard;
 local row = grafana.row;
@@ -394,8 +389,7 @@ local kp = (import 'kube-prometheus/main.libsonnet') + {
 
 As jsonnet is a superset of json, the jsonnet `import` function can be used to include Grafana dashboard json blobs. In this example we are importing a [provided example dashboard](../examples/example-grafana-dashboard.json).
 
-[embedmd]:# (../examples/grafana-additional-rendered-dashboard-example.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/grafana-additional-rendered-dashboard-example.jsonnet"
 local kp = (import 'kube-prometheus/main.libsonnet') + {
   values+:: {
     common+:: {
@@ -419,8 +413,8 @@ local kp = (import 'kube-prometheus/main.libsonnet') + {
 ```
 
 In case you have lots of json dashboard exported out from grafana UI the above approach is going to take lots of time to improve performance we can use `rawDashboards` field and provide it's value as json string by using `importstr`
-[embedmd]:# (../examples/grafana-additional-rendered-dashboard-example-2.jsonnet)
-```jsonnet
+
+```jsonnet mdox-exec="cat examples/grafana-additional-rendered-dashboard-example-2.jsonnet"
 local kp = (import 'kube-prometheus/main.libsonnet') + {
   values+:: {
     common+:: {
@@ -523,8 +517,7 @@ values+:: {
 
 Full example of including etcd mixin using method described above:
 
-[embedmd]:# (../examples/mixin-inclusion.jsonnet)
-```jsonnet
+```jsonnet mdox-exec="cat examples/mixin-inclusion.jsonnet"
 local addMixin = (import 'kube-prometheus/lib/mixin.libsonnet');
 local etcdMixin = addMixin({
   name: 'etcd',

docs/exposing-prometheus-alertmanager-grafana-ingress.md

@@ -104,7 +104,7 @@ k.core.v1.list.new([
 
 In order to expose Alertmanager and Grafana, simply create additional fields containing an ingress object, but simply pointing at the `alertmanager` or `grafana` instead of the `prometheus-k8s` Service. Make sure to also use the correct port respectively, for Alertmanager it is also `web`, for Grafana it is `http`. Be sure to also specify the appropriate external URL. Note that the external URL for grafana is set in a different way than the external URL for Prometheus or Alertmanager. See [ingress.jsonnet](../examples/ingress.jsonnet) for how to set the Grafana external URL.
 
-In order to render the ingress objects similar to the other objects use as demonstrated in the [main readme](../README.md#usage):
+In order to render the ingress objects similar to the other objects use as demonstrated in the [main readme](../README.md):
 
 ```
 { ['00namespace-' + name]: kp.kubePrometheus[name] for name in std.objectFields(kp.kubePrometheus) } +