From 7756b5ce04192a168add2b03d62d31dc47a1ec98 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lucas=20Serv=C3=A9n=20Mar=C3=ADn?= Date: Thu, 8 Jul 2021 12:15:17 +0200 Subject: [PATCH] docs: use consistent notes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit standardizes how we display a `note` in our docs. Previously, we used a mix of `_Note_:`, `__Note:__`, `> Note`, and `> **Note**:` among others. Now, all notes appear as `> **Note**:`. Signed-off-by: Lucas Servén Marín --- cmd/docs-gen/main.go | 2 +- docs/annotations.md | 4 ++-- docs/api.md | 2 +- docs/building_kilo.md | 2 +- docs/building_website.md | 2 +- docs/userspace-wireguard.md | 6 +++--- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/cmd/docs-gen/main.go b/cmd/docs-gen/main.go index fc6ab95a..054826db 100644 --- a/cmd/docs-gen/main.go +++ b/cmd/docs-gen/main.go @@ -32,7 +32,7 @@ const ( firstParagraph = `# API This document is a reference of the API types introduced by Kilo. -> Note this document is generated from code comments. When contributing a change to this document, please do so by changing the code comments.` +> **Note**: this document is generated from code comments. When contributing a change to this document, please do so by changing the code comments.` ) var ( diff --git a/docs/annotations.md b/docs/annotations.md index 548671d9..29037bf3 100644 --- a/docs/annotations.md +++ b/docs/annotations.md @@ -36,7 +36,7 @@ In some situations it may be desirable to manually select the leader for a locat * _firewall_: Kilo requires an open UDP port, which defaults to 51820, to communicate between locations; if only one node is configured to have that port open, then that node should be given the leader annotation; * _bandwidth_: if certain nodes in the cluster have a higher bandwidth or lower latency Internet connection, then those nodes should be given the leader annotation. -_Note_: multiple nodes within a single location can be given the leader annotation; in this case, Kilo will select one leader from the set of annotated nodes. +> **Note**: multiple nodes within a single location can be given the leader annotation; in this case, Kilo will select one leader from the set of annotated nodes. ### location Kilo allows nodes in different logical or physical locations to route packets to one-another. @@ -44,7 +44,7 @@ In order to know what connections to create, Kilo needs to know which nodes are Kilo will try to infer each node's location from the [topology.kubernetes.io/region](https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#topologykubernetesioregion) node label. If the label is not present for a node, for example if running a bare-metal cluster or on an unsupported cloud provider, then the location annotation should be specified. -_Note_: all nodes without a defined location will be considered to be in the default location `""`. +> **Note**: all nodes without a defined location will be considered to be in the default location `""`. ### persistent-keepalive In certain deployments, cluster nodes may be located behind NAT or a firewall, e.g. edge nodes located behind a commodity router. diff --git a/docs/api.md b/docs/api.md index 0dc13f51..dbb36517 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,7 +1,7 @@ # API This document is a reference of the API types introduced by Kilo. -> Note this document is generated from code comments. When contributing a change to this document, please do so by changing the code comments. +> **Note**: this document is generated from code comments. When contributing a change to this document, please do so by changing the code comments. ## Table of Contents * [DNSOrIP](#dnsorip) diff --git a/docs/building_kilo.md b/docs/building_kilo.md index 13d1f11b..526d5931 100644 --- a/docs/building_kilo.md +++ b/docs/building_kilo.md @@ -55,7 +55,7 @@ To execute basic end to end tests, run: ```shell make e2e ``` -__Note__: The end to end tests are currently flaky, so try running them again if they fail. +> **Note**: The end to end tests are currently flaky, so try running them again if they fail. To instead run all of the tests with a single command, run: ```shell diff --git a/docs/building_website.md b/docs/building_website.md index 415b48f4..fc293625 100644 --- a/docs/building_website.md +++ b/docs/building_website.md @@ -41,4 +41,4 @@ Then, regenerate the markdown for the website with the command: make website/docs/README.md ``` Edit `/website/sidebars.js` accordingly. -_Note:_ The `id` in the header file `/website/docs/` must match the `id` specified in `website/sidebars.js`. +> **Note**: The `id` in the header file `/website/docs/` must match the `id` specified in `website/sidebars.js`. diff --git a/docs/userspace-wireguard.md b/docs/userspace-wireguard.md index bd72587c..d9135b4c 100644 --- a/docs/userspace-wireguard.md +++ b/docs/userspace-wireguard.md @@ -13,7 +13,7 @@ One example of a userspace implementation of WireGuard is [BoringTun]. In a homogeneous cluster where no node has the WireGuard kernel module, a userspace WireGuard implementation can be made available by deploying a DaemonSet. This DaemonSet creates a WireGuard interface that Kilo will manage. -__Note:__ in order to avoid race conditions, `kg` needs to be passed the `--create-interface=false` flag. +> **Note**: in order to avoid race conditions, `kg` needs to be passed the `--create-interface=false` flag. An example configuration for a K3s cluster with [BoringTun] can be applied with: @@ -22,7 +22,7 @@ kubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/crd kubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/kilo-k3s-userspace.yaml ``` -__Note:__ even if some nodes have the WireGuard kernel module, this configuration will cause all nodes to use the userspace implementation of WireGuard. +> **Note**: even if some nodes have the WireGuard kernel module, this configuration will cause all nodes to use the userspace implementation of WireGuard. ## Heterogeneous Clusters @@ -39,6 +39,6 @@ It will also create two different DaemonSets with Kilo: 1. `kilo` without userspace WireGuard; and 1. `kilo-userspace` with [BoringTun] as a sidecar. -__Note:__ because Kilo is dependant on nkml, nkml must be run on the host network before CNI is available and requires a kubeconfig in order to access the Kubernetes API. +> **Note**: because Kilo is dependant on nkml, nkml must be run on the host network before CNI is available and requires a kubeconfig in order to access the Kubernetes API. [BoringTun]: https://github.com/cloudflare/boringtun