General docs cleanup

Reading through the book for the first time, I took the opportunity to
look at it with fresh eyes and find things that were missing or needed
an update.

This addresses various grammer, spelling, and linking issues found
throughout the book. There are some mdlint updates that were included
where they were very obvious, but that was not the scope of this effort.
If we want to go with full mdlinting, then that should be its own PR and
also include a job to make sure it's enforced.

Signed-off-by: Sean McGinnis <[email protected]>

Author: stmcginnis

docs/book/src/clusterctl/commands/completion.md

@@ -2,8 +2,7 @@
 
 The `clusterctl completion` command outputs shell completion code for the
 specified shell (bash or zsh). The shell code must be evaluated to provide
-interactive completion of clusterctl commands. This can be done by sourcing it
-from the `~/.bash_profile`.
+interactive completion of clusterctl commands.
 
 ## Bash
 
@@ -15,9 +14,10 @@ This requires the bash-completion framework.
 
 </aside>
 
-To install it on macOS use Homebrew:
+To install `bash-completion` on macOS, use Homebrew:
+
 ```
-$ brew install bash-completion
+brew install bash-completion
 ```
 
 Once installed, bash_completion must be evaluated. This can be done by adding

docs/book/src/clusterctl/commands/config-cluster.md

@@ -42,7 +42,7 @@ clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \
 
 ### Flavors
 
-The infrastructure provider authors can provide different type of cluster templates, or flavors; use the `--flavor` flag
+The infrastructure provider authors can provide different types of cluster templates, or flavors; use the `--flavor` flag
 to specify which flavor to use; e.g.
 
 ```
@@ -87,9 +87,9 @@ clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \
 
 ### Variables
 
-If the selected cluster template expects some environment variables, user should ensure those variables are set in advance.
+If the selected cluster template expects some environment variables, the user should ensure those variables are set in advance.
 
-e.g. if the `AWS_CREDENTIALS` variable is expected for a cluster template targeting the `aws` infrastructure, you
+E.g. if the `AWS_CREDENTIALS` variable is expected for a cluster template targeting the `aws` infrastructure, you
 should ensure the corresponding environment variable to be set before executing `clusterctl config cluster`.
 
 Please refer to the providers documentation for more info about the required variables or use the

docs/book/src/clusterctl/commands/delete.md

@@ -8,8 +8,8 @@ The operation is designed to prevent accidental deletion of user created objects
 clusterctl delete --infrastructure aws
 ```
 
-Deletes the AWS infrastructure provider components, while preserving the namespace where the provider components are hosted and
-the provider's CRDs.
+This command deletes the AWS infrastructure provider components, while preserving
+the namespace where the provider components are hosted and the provider's CRDs.
 
 <aside class="note warning">
 
@@ -19,7 +19,7 @@ If you want to delete the namespace where the provider components are hosted, yo
 
 Be aware that this operation deletes all the object existing in a namespace, not only the provider's components.
 
-</aside> 
+</aside>
 
 <aside class="note warning">
 
@@ -28,7 +28,7 @@ Be aware that this operation deletes all the object existing in a namespace, not
 If you want to delete the provider's CRDs, and all the components related to CRDs like e.g. the ValidatingWebhookConfiguration etc.,
 you can use the `--include-crd` flag.
 
-Be aware that this operation deletes all the object of Kind defined in the provider's CRDs, e.g. when deleting
+Be aware that this operation deletes all the objects of Kind's defined in the provider's CRDs, e.g. when deleting
 the aws provider, it deletes all the `AWSCluster`, `AWSMachine` etc.
 
 </aside>
@@ -39,12 +39,12 @@ the aws provider, it deletes all the `AWSCluster`, `AWSMachine` etc.
 
 KNOWN BUG:
 
-Deleting an infrastructure component from a namespace _that share
+Deleting an infrastructure component from a namespace _that shares
 the same prefix_ with other namespaces (e.g. `foo` and `foo-bar`) will result
 in erroneous deletion of cluster scoped objects such as `ClusterRole` and
 `ClusterRoleBindings` that share the same namespace prefix.
 
-This is true if the prefix before a dash `-` is same. That is, namespaces such
+This is true if the prefix before a dash `-` is the same. That is, namespaces such
 as `foo` and `foobar` are fine however namespaces such as `foo` and `foo-bar`
 are not.
 
@@ -60,7 +60,7 @@ For example,
     clusterctl delete --infrastructure aws --namespace foo
     ```
 
-ClusterRole and ClusterRoleBindings for both the namespaces are deleted.
+`ClusterRole` and `ClusterRoleBindings` for both the namespaces are deleted.
 
 See [issue 3119] for more details.
 

docs/book/src/clusterctl/commands/describe-cluster.md

@@ -1,13 +1,13 @@
 # clusterctl describe cluster
 
-The `clusterctl describe cluster` command provides an "at glance" view of a Cluster API cluster designed
+The `clusterctl describe cluster` command provides an "at a glance" view of a Cluster API cluster designed
 to help the user in quickly understanding if there are problems and where.
 
 For example `clusterctl describe cluster capi-quickstart` will provide an output similar to:
 
 ![](../../images/describe-cluster.png)
 
-The "at glance" view is based on the idea that clusterctl should avoid to overload the user with information,
+The "at a glance" view is based on the idea that clusterctl should avoid overloading the user with information,
 but instead surface problems, if any.
 
 In practice, if you look at the `ControlPlane` node, you might notice that the underlying machines

docs/book/src/clusterctl/commands/generate-yaml.md

@@ -9,7 +9,7 @@ example, this command can be leveraged in local and CI scripts or for
 development purposes.
 
 clusterctl ships with a simple yaml processor that performs variable
-substitution that takes into account of default values.
+substitution that takes into account default values.
 Under the hood, clusterctl's yaml processor uses
 [drone/envsubst][drone-envsubst] to replace variables and uses the defaults if
 necessary.

docs/book/src/clusterctl/commands/init.md

@@ -6,7 +6,7 @@ into a management cluster.
 This document provides more detail on how `clusterctl init` works and on the supported options for customizing your
 management cluster.
 
-## Defining the management cluster 
+## Defining the management cluster
 
 The `clusterctl init` command accepts in input a list of providers to install.
 
@@ -15,9 +15,9 @@ The `clusterctl init` command accepts in input a list of providers to install.
 <h1> Which providers can I use? </h1>
 
 You can use the `clusterctl config repositories` command to get a list of supported providers and their repository configuration.
- 
+
 If the provider of your choice is missing, you can customize the list of supported providers by using the
-[clusterctl configuration](../configuration.md) file. 
+[clusterctl configuration](../configuration.md) file.
 
 </aside>
 
@@ -79,15 +79,15 @@ provider name, e.g. `vsphere:v0.7.0-alpha.0`.
 
 #### Target namespace
 
-The `clusterctl init` command by default installs each provider in the default target namespace defined by each provider, e.g. `capi-system` for the Cluster API core provider. 
+The `clusterctl init` command by default installs each provider in the default target namespace defined by each provider, e.g. `capi-system` for the Cluster API core provider.
 
 See the provider documentation for more details.
 
 <aside class="note">
 
 <h1> Is it possible to change the target namespace ? </h1>
 
-You can specify the target namespace by using the `--target-namespace` flag. 
+You can specify the target namespace by using the `--target-namespace` flag.
 
 Please, note that the `--target-namespace` flag applies to all the providers to be installed during a `clusterctl init` operation.
 
@@ -104,7 +104,7 @@ same target namespace.
 
 #### Watching namespace
 
-The `clusterctl init` command by default installs each provider configured for watching objects in all namespaces. 
+The `clusterctl init` command by default installs each provider configured for watching objects in all namespaces.
 
 <aside class="note">
 
@@ -128,7 +128,7 @@ same namespace.
 ## Provider repositories
 
 To access provider specific information, such as the components YAML to be used for installing a provider,
-`clusterctl init` accesses the **provider repositories**, that are well-known places where the release assets for 
+`clusterctl init` accesses the **provider repositories**, that are well-known places where the release assets for
 a provider are published.
 
 See [clusterctl configuration](../configuration.md) for more info about provider repository configurations.
@@ -138,18 +138,18 @@ See [clusterctl configuration](../configuration.md) for more info about provider
 <h1> Is it possible to override files read from a provider repository? </h1>
 
 If, for any reasons, the user wants to replace the assets available on a provider repository with a locally available asset,
-the user is required to save the file under `$HOME/.cluster-api/overrides/<provider-label>/<version>/<file-name.yaml>`. 
+the user is required to save the file under `$HOME/.cluster-api/overrides/<provider-label>/<version>/<file-name.yaml>`.
 
 ```
-$HOME/.cluster-api/overrides//infrastructure-aws/v0.5.2/infrastructure-components.yaml
+$HOME/.cluster-api/overrides/infrastructure-aws/v0.5.2/infrastructure-components.yaml
 ```
 
 </aside>
 
 ## Variable substitution
-Providers can use variables in the components YAML published in the provider's repository. 
+Providers can use variables in the components YAML published in the provider's repository.
 
-During `clusterctl init`, those variables are replaced with environment variables or with variables read from the 
+During `clusterctl init`, those variables are replaced with environment variables or with variables read from the
 [clusterctl configuration](../configuration.md).
 
 <aside class="note warning">
@@ -164,7 +164,7 @@ The user should ensure the variables required by a provider are set in advance.
 
 <h1> How can I known which variables a provider requires? </h1>
 
-Users can refer to the provider documentation for the list of variables to be set or use the 
+Users can refer to the provider documentation for the list of variables to be set or use the
 `clusterctl config provider <provider-name>` command to get a list of expected variable names.
 
 </aside>
@@ -175,23 +175,23 @@ When installing a provider, the `clusterctl init` command executes a set of step
 the lifecycle management of the provider's components.
 
 * All the provider's components are labeled, so they can be easily identified in
-subsequent moments of the provider's lifecycle, e.g. upgrades. 
-  
+subsequent moments of the provider's lifecycle, e.g. upgrades.
+
  ```bash
  labels:
  - clusterctl.cluster.x-k8s.io: ""
  - cluster.x-k8s.io/provider: "<provider-name>"
  ```
-  
+
 * An additional `Provider` object is created in the target namespace where the provider is installed.
 This object keeps track of the provider version, the watching namespace, and other useful information
-for the inventory of the providers currently installed in the management cluster.  
+for the inventory of the providers currently installed in the management cluster.
 
 <aside class="note warning">
 
 <h1>Warning</h1>
 
 The `clusterctl.cluster.x-k8s.io` labels, the `cluster.x-k8s.io/provider` labels and the `Provider` objects MUST NOT be altered.
-If this happens, there are no guarantees about the proper functioning of `clusterctl`.  
+If this happens, there are no guarantees about the proper functioning of `clusterctl`.
 
 </aside>

docs/book/src/clusterctl/commands/move.md

@@ -9,7 +9,7 @@ MachineDeployments, etc. from one management cluster to another management clust
 
 Before running `clusterctl move`, the user should take care of preparing the target management cluster, including also installing
 all the required provider using `clusterctl init`.
- 
+
 The version of the providers installed in the target management cluster should be at least the same version of the
 corresponding provider in the source cluster.
 
@@ -29,10 +29,10 @@ to move the Cluster API objects defined in another namespace, you can use the `-
 <h1> Pause Reconciliation </h1>
 
 Before moving a `Cluster`, clusterctl sets the `Cluster.Spec.Paused` field to `true` stopping
-the controllers to reconcile the workload cluster _in the source management cluster_.
+the controllers from reconciling the workload cluster _in the source management cluster_.
 
 The `Cluster` object created in the target management cluster instead will be actively reconciled as soon as the move
-process completes. 
+process completes.
 
 </aside>
 
@@ -58,7 +58,7 @@ This can now be achieved with the following procedure:
 3. Use `clusterctl config cluster ... | kubectl apply -f -` to provision a target management cluster
 4. Wait for the target management cluster to be up and running
 5. Get the kubeconfig for the new target management cluster
-6. Use `clusterctl init` with the new cluster's kubeconfig to install the provider components 
+6. Use `clusterctl init` with the new cluster's kubeconfig to install the provider components
 7. Use `clusterctl move` to move the Cluster API resources from the bootstrap cluster to the target management cluster
 8. Delete the bootstrap cluster
 

docs/book/src/clusterctl/configuration.md

@@ -1,6 +1,7 @@
 # clusterctl Configuration File
 
-The `clusterctl` config file is located at `$HOME/.cluster-api/clusterctl.yaml` and it can be used to:
+The `clusterctl` config file is located at `$HOME/.cluster-api/clusterctl.yaml`.
+It can be used to:
 
 - Customize the list of providers and provider repositories.
 - Provide configuration values to be used for variable substitution when installing providers or creating clusters.
@@ -34,7 +35,7 @@ See [provider contract](provider-contract.md) for instructions about how to set
 
 ## Variables
 
-When installing a provider `clusterctl` reads a YAML file that is published in the provider repository; while executing
+When installing a provider `clusterctl` reads a YAML file that is published in the provider repository. While executing
 this operation, `clusterctl` can substitute certain variables with the ones provided by the user.
 
 The same mechanism also applies when `clusterctl` reads the cluster templates YAML published in the repository, e.g.
@@ -48,7 +49,8 @@ variables in the `clusterctl` config file:
 AWS_B64ENCODED_CREDENTIALS: XXXXXXXX
 ```
 
-In case a variable is defined both in the config file and as an OS environment variable, the latter takes precedence.
+In case a variable is defined both in the config file and as an OS environment variable,
+the environment variable takes precedence.
 
 ## Overrides Layer
 
@@ -57,11 +59,14 @@ cluster templates and metadata. By default, it reads the files from
 `$HOME/.cluster-api/overrides`.
 
 The directory structure under the `overrides` directory should follow the
-template
+template:
+
 ```
 <providerType-providerName>/<version>/<fileName>
 ```
+
 For example,
+
 ```
 ├── bootstrap-kubeadm
 │   └── v0.3.0
@@ -78,37 +83,39 @@ For example,
             └── infrastructure-components.yaml
 ```
 
-For developers who want to generate the overrides layer, see [Run the
-local-overrides hack!](developers.md#run-the-local-overrides-hack).
+For developers who want to generate the overrides layer, see
+[Build artifacts locally](developers.md#build-artifacts-locally).
 
 Once these overrides are specified, `clusterctl` will use them instead of
 getting the values from the default or specified providers.
 
 One example usage of the overrides layer is that it allows you to deploy
 clusters with custom templates that may not be available from the official
 provider repositories.
-For example, you can now do
+For example, you can now do:
+
 ```bash
 clusterctl config cluster mycluster --flavor dev --infrastructure aws:v0.5.0 -v5
 ```
 
 The `-v5` provides verbose logging which will confirm the usage of the
 override file.
+
 ```bash
 Using Override="cluster-template-dev.yaml" Provider="infrastructure-aws" Version="v0.5.0"
 ```
 
 Another example, if you would like to deploy a custom version of CAPA, you can
 make changes to `infrastructure-components.yaml` in the overrides folder and
 run,
+
 ```bash
 clusterctl init --infrastructure aws:v0.5.0 -v5
 ...
 Using Override="infrastructure-components.yaml" Provider="infrastructure-aws" Version="v0.5.0"
 ...
 ```
 
-
 If you prefer to have the overrides directory at a different location (e.g.
 `/Users/foobar/workspace/dev-releases`) you can specify the overrides
 directory in the clusterctl config file as
@@ -177,9 +184,8 @@ The value string is a possibly signed sequence of decimal numbers, each with opt
 
 If no value is specified or the format is invalid, the default value of 10 minutes will be used.
 
-
 ## Debugging/Logging
 
 To have more verbose logs you can use the `-v` flag when running the `clusterctl` and set the level of the logging verbose with a positive integer number, ie. `-v 3`.
 
-If you do not want to use the flag every time you issue a command you can set the environment variable `CLUSTERCTL_LOG_LEVEL` or set the variable in the `clusterctl` config file which is located by default at `$HOME/.cluster-api/clusterctl.yaml`.
+If you do not want to use the flag every time you issue a command you can set the environment variable `CLUSTERCTL_LOG_LEVEL` or set the variable in the `clusterctl` config file located by default at `$HOME/.cluster-api/clusterctl.yaml`.