Merge pull request #1453 from saswatamcode/add-mdox

Author: paulfantom

.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

@@ -4,12 +4,12 @@ Kube-prometheus has a somehow predictable release schedule, releases were
 historically cut in sync with OpenShift releases as per downstream needs. So
 far there hasn't been any problem with this schedule since it is also in sync
 with Kubernetes releases. So for every new Kubernetes release, there is a new
-release of kube-prometheus, although it tends to happen later. 
+release of kube-prometheus, although it tends to happen later.
 
 # How to cut a new release
 
 > This guide is strongly based on the [prometheus-operator release
-instructions](https://github.com/prometheus-operator/prometheus-operator/blob/master/RELEASE.md).
+> instructions](https://github.com/prometheus-operator/prometheus-operator/blob/master/RELEASE.md).
 
 ## Branch management and versioning strategy
 
@@ -53,19 +53,19 @@ failed or because the main branch was already up-to-date.
 The main branch of kube-prometheus should support the last 2 versions of
 Kubernetes. We need to make sure that the CI on the main branch is testing the
 kube-prometheus configuration against both of these versions by updating the [CI
-worklow](/.github/workflows/ci.yaml) to include the latest kind version and the
+worklow](.github/workflows/ci.yaml) to include the latest kind version and the
 2 latest images versions that are attached to the kind release. Once that is
-done, the [compatibility matrix](/README.md#kubernetes-compatibility-matrix) in
+done, the [compatibility matrix](README.md#kubernetes-compatibility-matrix) in
 the README should also be updated to reflect the CI changes.
 
 ## Create pull request to cut the release
 
 ### Pin Jsonnet dependencies
 
 Pin jsonnet dependencies in
-[jsonnetfile.json](/jsonnet/kube-prometheus/jsonnetfile.json). Each dependency
+[jsonnetfile.json](jsonnet/kube-prometheus/jsonnetfile.json). Each dependency
 should be pinned to the latest release branch or if it doesn't have one, pinned
-to the latest commit. 
+to the latest commit.
 
 ### Start with a fresh environment
 
@@ -87,14 +87,14 @@ make generate
 
 ### Update the compatibility matrix
 
-Update the [compatibility matrix](/README.md#kubernetes-compatibility-matrix) in
+Update the [compatibility matrix](README.md#kubernetes-compatibility-matrix) in
 the README, by adding the new release based on the `main` branch compatibility
 and removing the oldest release branch to only keep the latest 5 branches in the
 matrix.
 
 ### Update changelog
 
-Iterate over the PRs that were merged between the latest release of kube-prometheus and the HEAD and add the changelog entries to the [CHANGELOG](/CHANGELOG.md).
+Iterate over the PRs that were merged between the latest release of kube-prometheus and the HEAD and add the changelog entries to the [CHANGELOG](CHANGELOG.md).
 
 ## Create release branch
 
@@ -111,10 +111,10 @@ the main branch to be in sync with the latest changes of its dependencies.
 
 ### Update CI workflow
 
-Update the [versions workflow](/.github/workflows/versions.yaml) to include the latest release branch and remove the oldest one to reflect the list of supported releases.
+Update the [versions workflow](.github/workflows/versions.yaml) to include the latest release branch and remove the oldest one to reflect the list of supported releases.
 
 ### Update Kubernetes versions used by kubeconform
 
 Update the versions of Kubernetes used when validating manifests with
-kubeconform in the [Makefile](/Makefile) to align with the compatibility
+kubeconform in the [Makefile](Makefile) to align with the compatibility
 matrix.

RELEASE.md

@@ -33,8 +33,8 @@ This code of conduct applies both within project spaces and in public spaces
 when an individual is representing the project or its community.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting a project maintainer listed in 
-https://github.com/prometheus-operator/prometheus-operator/blob/master/MAINTAINERS.md. 
+reported by contacting a project maintainer listed in
+https://github.com/prometheus-operator/prometheus-operator/blob/master/MAINTAINERS.md.
 
 This Code of Conduct is adapted from the Contributor Covenant
 (http://contributor-covenant.org), version 1.2.0, available at

code-of-conduct.md

@@ -20,15 +20,14 @@ After your workspace start, you can deploy a kube-prometheus inside a Kind clust
 
 If you are reviewing a PR, you'll have a fully-functional kubernetes cluster, generating real monitoring data that can be used to review if the proposed changes works as described.
 
-If you are working on new features/bug fixes, you can regenerate kube-prometheus's YAML manifests with `make generate` and deploy it again with `make deploy`. 
+If you are working on new features/bug fixes, you can regenerate kube-prometheus's YAML manifests with `make generate` and deploy it again with `make deploy`.
 
 ## Gitpod
 
 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`
 
 ![image](https://user-images.githubusercontent.com/24193764/135534546-4f6bf0e5-57cd-4e35-ad80-88bd47d64276.png)
-

developer-workspace/README.md

@@ -4,9 +4,9 @@ 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
+You can monitor the `awscni` using kube-promethus with :
+
+```jsonnet mdox-exec="cat examples/eks-cni-example.jsonnet"
 local kp = (import 'kube-prometheus/main.libsonnet') + {
   values+:: {
     common+: {

docs/EKS-cni-support.md

@@ -5,6 +5,7 @@ authentication. Until it does, Prometheus must use HTTP (not HTTPS)
 for scraping.
 
 You can configure this behavior through kube-prometheus with:
+
 ```
 local kp = (import 'kube-prometheus/kube-prometheus.libsonnet') +
     (import 'kube-prometheus/kube-prometheus-insecure-kubelet.libsonnet') +

docs/GKE-cadvisor-support.md

@@ -1,16 +1,16 @@
 ---
-title: "Blackbox Exporter"
-description: "Generated API docs for the Prometheus Operator"
-lead: "This Document documents the types introduced by the Prometheus Operator to be consumed by users."
-date: 2021-03-08T08:49:31+00:00
-lastmod: 2021-03-08T08:49:31+00:00
-draft: false
-images: []
-menu:
-  docs:
-    parent: "kube"
 weight: 630
 toc: true
+title: Blackbox Exporter
+menu:
+    docs:
+        parent: kube
+lead: This Document documents the types introduced by the Prometheus Operator to be consumed by users.
+lastmod: "2021-03-08T08:49:31+00:00"
+images: []
+draft: false
+description: Generated API docs for the Prometheus Operator
+date: "2021-03-08T08:49:31+00:00"
 ---
 
 # Setting up a blackbox exporter
@@ -21,6 +21,7 @@ The `prometheus-operator` defines a `Probe` resource type that can be used to de
 
 1. Override blackbox-related configuration parameters as needed.
 2. Add the following to the list of renderers to render the blackbox exporter manifests:
+
 ```
 { ['blackbox-exporter-' + name]: kp.blackboxExporter[name] for name in std.objectFields(kp.blackboxExporter) }
 ```