Merge pull request #3037 from multani/improve-doc

📖 Improve rendering of the documentation

docs/book/src/SUMMARY.md

@@ -26,7 +26,7 @@
   - [Implementing defaulting/validating webhooks](./cronjob-tutorial/webhook-implementation.md)
   - [Running and deploying the controller](./cronjob-tutorial/running.md)
 
-    - [Deploying the cert manager](./cronjob-tutorial/cert-manager.md)
+    - [Deploying cert-manager](./cronjob-tutorial/cert-manager.md)
     - [Deploying webhooks](./cronjob-tutorial/running-webhook.md)
 
   - [Writing tests](./cronjob-tutorial/writing-tests.md)
@@ -109,15 +109,15 @@
 - [Plugins][plugins]
 
   - [Available Plugins](./plugins/available-plugins.md)
-    - [To create a project](./docs/invalid)
+    - [To scaffold a project](./plugins/to-scaffold-project.md)
       - [go/v2 (Deprecated)](./plugins/go-v2-plugin.md)
       - [go/v3 (Default init scaffold)](./plugins/go-v3-plugin.md)
       - [go/v4-alpha](./plugins/go-v4-plugin.md)
-    - [To add optional features](./docs/invalid)
+    - [To add optional features](./plugins/to-add-optional-features.md)
       - [declarative/v1](./plugins/declarative-v1.md)
       - [grafana/v1-alpha](./plugins/grafana-v1-alpha.md)
       - [deploy-image/v1-alpha](./plugins/deploy-image-plugin-v1-alpha.md)
-    - [To be extended for others tools](./docs/invalid)
+    - [To be extended for others tools](./plugins/to-be-extended.md)
       - [kustomize/v1](./plugins/kustomize-v1.md)
       - [kustomize/v2-alpha](./plugins/kustomize-v2-alpha.md)
   - [Extending the CLI](./plugins/extending-cli.md)

docs/book/src/component-config-tutorial/api-changes.md

@@ -57,7 +57,7 @@ loading the config from the file.
 
 </aside>
 
-Lastly, we'll change the `NewManager` call to use the `options` varible we
+Lastly, we'll change the `NewManager` call to use the `options` variable we
 defined above.
 
 ```go
@@ -106,13 +106,16 @@ configMapGenerator:
   - controller_manager_config.yaml
 ```
 
-Update the file `default/kustomization.yaml` by adding under the patchesStrategicMerge: the following patch:
+Update the file `default/kustomization.yaml` by adding under the [`patchesStrategicMerge:` key](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_patchesstrategicmerge_) the following patch:
 
+```yaml
+patchesStrategicMerge:
 # Mount the controller config file for loading manager configurations
 # through a ComponentConfig type
 - manager_config_patch.yaml
+```
 
-Update the file `default/manager_config_patch.yaml` by adding under the spec: the following patch:
+Update the file `default/manager_config_patch.yaml` by adding under the `spec:` key the following patch:
 
 ```yaml
 spec:
@@ -131,4 +134,3 @@ spec:
         configMap:
           name: manager-config
 ```
-

docs/book/src/cronjob-tutorial/basic-project.md

@@ -7,22 +7,22 @@ basic pieces of boilerplate.
 
 First up, basic infrastructure for building your project:
 
-<details> <summary>`go.mod`: A new Go module matching our project, with
+<details><summary><code>go.mod</code>: A new Go module matching our project, with
 basic dependencies</summary>
 
 ```go
 {{#include ./testdata/project/go.mod}}
 ```
 </details>
 
-<details><summary>`Makefile`: Make targets for building and deploying your controller</summary>
+<details><summary><code>Makefile</code>: Make targets for building and deploying your controller</summary>
 
 ```makefile
 {{#include ./testdata/project/Makefile}}
 ```
 </details>
 
-<details><summary>`PROJECT`: Kubebuilder metadata for scaffolding new components</summary>
+<details><summary><code>PROJECT</code>: Kubebuilder metadata for scaffolding new components</summary>
 
 ```yaml
 {{#include ./testdata/project/PROJECT}}

docs/book/src/cronjob-tutorial/cert-manager.md

@@ -1,24 +1,29 @@
-# Deploying the cert manager
+# Deploying cert-manager
 
-We suggest using [cert manager](https://github.com/jetstack/cert-manager) for
+We suggest using [cert-manager](https://github.com/jetstack/cert-manager) for
 provisioning the certificates for the webhook server. Other solutions should
 also work as long as they put the certificates in the desired location.
 
 You can follow
-[the cert manager documentation](https://cert-manager.io/docs/installation/)
+[the cert-manager documentation](https://cert-manager.io/docs/installation/)
 to install it.
 
-Cert manager also has a component called CA injector, which is responsible for
-injecting the CA bundle into the Mutating|ValidatingWebhookConfiguration.
+cert-manager also has a component called [CA
+Injector](https://cert-manager.io/docs/concepts/ca-injector/), which is responsible for
+injecting the CA bundle into the [`MutatingWebhookConfiguration`](https://pkg.go.dev/k8s.io/api/admissionregistration/v1#MutatingWebhookConfiguration)
+/ [`ValidatingWebhookConfiguration`](https://pkg.go.dev/k8s.io/api/admissionregistration/v1#ValidatingWebhookConfiguration).
 
 To accomplish that, you need to use an annotation with key
 `cert-manager.io/inject-ca-from`
-in the Mutating|ValidatingWebhookConfiguration objects.
-The value of the annotation should point to an existing certificate CR instance
+in the [`MutatingWebhookConfiguration`](https://pkg.go.dev/k8s.io/api/admissionregistration/v1#MutatingWebhookConfiguration)
+/ [`ValidatingWebhookConfiguration`](https://pkg.go.dev/k8s.io/api/admissionregistration/v1#ValidatingWebhookConfiguration) objects.
+The value of the annotation should point to an existing [certificate request instance](https://cert-manager.io/docs/concepts/certificaterequest/)
 in the format of `<certificate-namespace>/<certificate-name>`.
 
 This is the [kustomize](https://github.com/kubernetes-sigs/kustomize) patch we
-used for annotating the Mutating|ValidatingWebhookConfiguration objects.
+used for annotating the [`MutatingWebhookConfiguration`](https://pkg.go.dev/k8s.io/api/admissionregistration/v1#MutatingWebhookConfiguration)
+/ [`ValidatingWebhookConfiguration`](https://pkg.go.dev/k8s.io/api/admissionregistration/v1#ValidatingWebhookConfiguration) objects.
+
 ```yaml
 {{#include ./testdata/project/config/default/webhookcainjection_patch.yaml}}
 ```

docs/book/src/cronjob-tutorial/cronjob-tutorial.md

@@ -53,15 +53,18 @@ kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io
 ```
 
 <aside class="note">
+
 Your project's name defaults to that of your current working directory.
 You can pass `--project-name=<dns1123-label-string>` to set a different project name.
+
 </aside>
 
 Now that we've got a project in place, let's take a look at what
 Kubebuilder has scaffolded for us so far...
 
 <aside class="note">
-<h1>Developing in $GOPATH</h1>
+
+<h1>Developing in <code>$GOPATH</code></h1>
 
 If your project is initialized within [`GOPATH`][GOPATH-golang-docs], the implicitly called `go mod init` will interpolate the module path for you.
 Otherwise `--repo=<module path>` must be set.

docs/book/src/cronjob-tutorial/running-webhook.md

@@ -10,9 +10,9 @@ Why?
 - You can tear it down in seconds.
 - You don't need to push your images to remote registry.
 
-## Cert Manager
+## cert-manager
 
-You need to follow [this](./cert-manager.md) to install the cert manager bundle.
+You need to follow [this](./cert-manager.md) to install the cert-manager bundle.
 
 ## Build your image
 

docs/book/src/cronjob-tutorial/testdata/emptymain.go

@@ -20,7 +20,7 @@ limitations under the License.
 Our package starts out with some basic imports.  Particularly:
 
 - The core [controller-runtime](https://pkg.go.dev/sigs.k8s.io/controller-runtime?tab=doc) library
-- The default controller-runtime logging, Zap (more on that a bit later)
+- The default controller-runtime logging, [Zap](https://pkg.go.dev/go.uber.org/zap) (more on that a bit later)
 
 */
 
@@ -117,7 +117,7 @@ func main() {
 	}
 
 	/*
-		Note that the Manager can restrict the namespace that all controllers will watch for resources by:
+		Note that the `Manager` can restrict the namespace that all controllers will watch for resources by:
 	*/
 
 	mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
@@ -131,12 +131,13 @@ func main() {
 	})
 
 	/*
-		The above example will change the scope of your project to a single Namespace. In this scenario,
+		The above example will change the scope of your project to a single `Namespace`. In this scenario,
 		it is also suggested to restrict the provided authorization to this namespace by replacing the default
-		ClusterRole and ClusterRoleBinding to Role and RoleBinding respectively.
-		For further information see the kubernetes documentation about Using [RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).
+		`ClusterRole` and `ClusterRoleBinding` to `Role` and `RoleBinding` respectively.
+		For further information see the Kubernetes documentation about Using [RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).
 
-		Also, it is possible to use the MultiNamespacedCacheBuilder to watch a specific set of namespaces:
+		Also, it is possible to use the [`MultiNamespacedCacheBuilder`](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/cache#MultiNamespacedCacheBuilder)
+		to watch a specific set of namespaces:
 	*/
 
 	var namespaces []string // List of Namespaces
@@ -152,7 +153,7 @@ func main() {
 	})
 
 	/*
-		For further information see [MultiNamespacedCacheBuilder](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/cache?tab=doc#MultiNamespacedCacheBuilder)
+		For further information see [`MultiNamespacedCacheBuilder`](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/cache?tab=doc#MultiNamespacedCacheBuilder)
 	*/
 
 	// +kubebuilder:scaffold:builder

docs/book/src/multiversion-tutorial/tutorial.md

@@ -34,7 +34,7 @@ a [feature gate][kube-feature-gates]), and became beta in Kubernetes 1.15
 
 If you're on Kubernetes 1.13-1.14, make sure to enable the feature gate.
 If you're on Kubernetes 1.12 or below, you'll need a new cluster to use
-conversion. Check out the [KinD instructions](/reference/kind.md) for
+conversion. Check out the [kind instructions](/reference/kind.md) for
 instructions on how to set up a all-in-one cluster.
 
 </aside>

docs/book/src/plugins/available-plugins.md

@@ -2,58 +2,6 @@
 
 This section describes the plugins supported and shipped in with the Kubebuilder project.
 
-## To scaffold the projects
-
-The following plugins are useful to scaffold the whole project with the tool.
-
-| Plugin                                                                             | Key                  | Description                                                                                                                                                                                                                                  |
-| ---------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [go.kubebuilder.io/v2 - (Deprecated)](go-v2-plugin.md)                             | `go/v2`              | Golang plugin responsible for scaffolding the legacy layout provided with Kubebuilder CLI >= `2.0.0` and < `3.0.0`.                                                                                                                          |
-| [go.kubebuilder.io/v3 - (Default scaffold with Kubebuilder init)](go-v3-plugin.md) | `go/v3`              | Default scaffold used for creating a project when no plugin(s) are provided. Responsible for scaffolding Golang projects and its configurations.                                                                                             |
-| [go.kubebuilder.io/v4-alpha - (Add Apple Sillicom Support)](go-v4-plugin.md)       | `go/v4`              | Scaffold composite by `base.go.kubebuilder.io/v3` and [kustomize.common.kubebuilder.io/v2-alpha](kustomize-v2-alpha.md). Responsible for scaffolding Golang projects and its configurations.                                                                                             |
-
-## To add optional features
-
-The following plugins are useful to generate code and take advantage of optional features
-
-| Plugin                                                                             | Key                  | Description                                                                                                                                                                                                                                  |
-| ---------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [declarative.go.kubebuilder.io/v1](declarative-v1.md)                              | `declarative/v1`     | Optional plugin used to scaffold APIs/controllers using the [kubebuilder-declarative-pattern][kubebuilder-declarative-pattern] project.                                                                                                      |
-| [grafana.kubebuilder.io/v1-alpha](grafana-v1-alpha.md)                             | `grafana/v1-alpha`   | Optional helper plugin which can be used to scaffold Grafana Manifests Dashboards for the default metrics which are exported by controller-runtime.                                                                                                 |
-| [deploy-image.go.kubebuilder.io/v1-alpha](deploy-image-plugin-v1-alpha)            | `deploy-image/v1-alpha`   | Optional helper plugin which can be used to scaffold APIs and controller with code implementation to Deploy and Manage an Operand(image).                                                                                                 |
-
-## To help projects using Kubebuilder as Lib to composite new solutions and plugins
-
-<aside class="note">
-
-<h1>You can also create your own plugins, see:</h1>
-
-- [Creating your own plugins][create-plugins].
-
-</aside>
-
-Then, see that you can use the kustomize plugin, which is responsible for to scaffold the kustomize files under `config/`, as
-the base language plugins which are responsible for to scaffold the Golang files to create your own plugins to work with
-another languages (i.e. [Operator-SDK][sdk] does to allow users work with Ansible/Helm) or to add
-helpers on top, such as [Operator-SDK][sdk] does to add their features to integrate the projects with [OLM][olm].
-
-| Plugin                                                                             | Key                  | Description                                                                                                                                                                                                                                  |
-| ---------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [kustomize.common.kubebuilder.io/v1](kustomize-v1.md)                              | `kustomize/v1`       | Responsible for scaffold all manifests to configure the projects with [kustomize(v3)][kustomize]. (create and update the `config/` directory). This plugin is used in the composition to create the plugin (`go/v3`).                    |
-| [kustomize.common.kubebuilder.io/v2-alpha](kustomize-v2-alpha.md)                  | `kustomize/v2-alpha` | It has the same purpose of `kustomize/v1`. However, it works with [kustomize][kustomize] version `v4` and addresses the required changes for future kustomize configurations. It will probably be used with the future `go/v4-alpha` plugin. |
-| `base.go.kubebuilder.io/v3`                                                        | `base/v3`            | Responsible for scaffold all files which specific requires Golang. This plugin is used in the composition to create the plugin (`go/v3`)                                                                                                     |
-
-<aside class="note">
-
-<h1>Plugins Versioning</h1>
-
-**ALPHA** plugins can introduce breaking changes. For further info see [Plugins Versioning](./plugins/plugins-versioning.md).
-
-</aside>
-
-[create-plugins]: creating-plugins.md
-[kubebuilder-declarative-pattern]: https://github.com/kubernetes-sigs/kubebuilder-declarative-pattern
-[kustomize]: https://kustomize.io/
-[sdk]: https://github.com/operator-framework/operator-sdk
-[olm]: https://olm.operatorframework.io/
-
+{{#include to-scaffold-project.md }}
+{{#include to-add-optional-features.md }}
+{{#include to-be-extended.md }}

docs/book/src/plugins/creating-plugins.md

@@ -1,8 +1,16 @@
 # Creating your own plugins
 
+[extending-cli]: extending-cli.md
+[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
+[operator-pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator
+[sdk-ansible]: https://sdk.operatorframework.io/docs/building-operators/ansible/
+[sdk-cli-pkg]: https://pkg.go.dev/github.com/operator-framework/operator-sdk/internal/cmd/operator-sdk/cli
+[sdk-helm]: https://sdk.operatorframework.io/docs/building-operators/helm/
+[sdk]: https://github.com/operator-framework/operator-sdk
+
 ## Overview
 
-You can extend the Kubebuilder API to create your own plugins. If [extending the CLI][extending-cli], your plugin will be implemented in your project and registered to the CLI as has been done by the [SDK][sdk] project. See its [cli code][sdk-cli-pkg] as an example.
+You can extend the Kubebuilder API to create your own plugins. If [extending the CLI][extending-cli], your plugin will be implemented in your project and registered to the CLI as has been done by the [SDK][sdk] project. See its [CLI code][sdk-cli-pkg] as an example.
 
 ## Language-based Plugins
 
@@ -44,23 +52,21 @@ And then, you will also be able to use custom plugins and options currently or i
 
 Note that users are also able to use plugins to customize their scaffolds and address specific needs.
 
-See that Kubebuilder provides the [deploy-image][deploy-image] plugin that allows the user to create the controller & CRs which will deploy and manage an image on the cluster:
+See that Kubebuilder provides the [`deploy-image`][deploy-image] plugin that allows the user to create the controller & CRs which will deploy and manage an image on the cluster:
 
 ```sh
 kubebuilder create api --group example.com --version v1alpha1 --kind Memcached --image=memcached:1.6.15-alpine --image-container-command="memcached,-m=64,modern,-v" --image-container-port="11211" --run-as-user="1001" --plugins="deploy-image/v1-alpha"
 ```
 
-This plugin will perform a custom scaffold following the [Operator Pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator).
+This plugin will perform a custom scaffold following the [Operator Pattern][operator-pattern].
 
-Another example is the [grafana][grafana] plugin that scaffolds a new folder container manifests to visualize operator status on Grafana Web UI:
+Another example is the [`grafana`][grafana] plugin that scaffolds a new folder container manifests to visualize operator status on Grafana Web UI:
 
 ```sh
 kubebuilder edit --plugins="grafana.kubebuilder.io/v1-alpha"
 ```
 
 In this way, by [Extending the Kubebuilder CLI][extending-cli], you can also create custom plugins such this one.
 
-Feel free to check the implementation under:
-
-- deploy-image: <https://github.com/kubernetes-sigs/kubebuilder/tree/v3.7.0/pkg/plugins/golang/deploy-image/v1alpha1>
-- grafana: <https://github.com/kubernetes-sigs/kubebuilder/tree/v3.7.0/pkg/plugins/optional/grafana/v1alpha>
+[grafana]: https://github.com/kubernetes-sigs/kubebuilder/tree/v3.7.0/pkg/plugins/optional/grafana/v1alpha
+[deploy-image]: https://github.com/kubernetes-sigs/kubebuilder/tree/v3.7.0/pkg/plugins/golang/deploy-image/v1alpha1