Add markers docs pages

This actually adds marker docs pages, and enables the markderdocs plugin.

Author: DirectXMan12

docs/book/book.toml

@@ -10,3 +10,6 @@ curly-quotes = true
 
 [preprocessor.literatego]
 command = "./litgo.sh"
+
+[preprocessor.markerdocs]
+command = "./markerdocs.sh"

docs/book/src/SUMMARY.md

@@ -42,6 +42,14 @@
   - [Kind cluster](reference/kind.md)
   - [What's a webhook?](reference/webhook-overview.md)
     - [Admission webhook](reference/admission-webhook.md)
+  - [Markers for Config/Code Generation](./reference/markers.md)
+
+      - [CRD Generation](./reference/markers/crd.md)
+      - [CRD Validation](./reference/markers/crd-validation.md)
+      - [Webhook](./reference/markers/webhook.md)
+      - [Object/DeepCopy](./reference/markers/object.md)
+      - [RBAC](./reference/markers/rbac.md)
+
 ---
 
 [Appendix: The TODO Landing Page](./TODO.md)

docs/book/src/reference/markers.md

@@ -0,0 +1,84 @@
+# Markers for Config/Code Generation
+
+KubeBuilder makes use of a tool called `controller-gen` (from
+[controller-tools](https://godoc.org/sigs.k8s.io/controller-tools)) for
+generating utility code and Kubernetes YAML.  This code and config
+generation is controlled by the presenence of special "marker comments" in
+Go code.
+
+Markers are single-line comments that start with a plus, followed by
+a marker name, optionally followed by some marker specific configuration:
+
+```go
+// +kubebuilder:validation:Optional
+// +kubebuilder:validation:MaxItems=2
+// +kubebuilder:printcolumn:JSONPath=".status.replicas",name=Replicas,type=string
+```
+
+See each subsection for information about different types of code and YAML
+generation.
+
+## Generating Code & Artifacts in KubeBuilder
+
+KubeBuilder projects have two `make` targets that make use of
+controller-gen:
+
+- `make manifests` generates Kubernetes object YAML, like
+  [CustomResourceDefinitions](./markers/crd.md),
+  [WebhookConfigurations](./markers/webhook.md), and [RBAC
+  roles](./markers/rbac.md).
+
+- `make generate` generates code, like [runtime.Object/DeepCopy
+  implementations](./markers/object.md).
+
+See [Generating CRDs](./generating-crd.md) for a comprehensive overview.
+
+## Marker Syntax
+
+Exact syntax is described in the [godocs for
+controller-tools](https://godoc.org/sigs.k8s.io/controller-tools/pkg/markers).
+
+In general, markers may either be: 
+
+- **Empty** (`+kubebuilder:validation:Optional`): empty markers are like boolean flags on the command line
+  -- just specifying them enables some behavior.
+
+- **Anonymous** (`+kubebuilder:validation:MaxItems=2`): anonymous markers take
+  a single value as their argument.
+
+- **Multi-option**
+  (`+kubebuilder:printcolumn:JSONPath=".status.replicas",name=Replicas,type=string`): multi-option
+  markers take one or more named arguments.  The first argument is
+  separated from the name by a colon, and latter arguments are
+  comma-separated.  Order of arguments doesn't matter.  Some arguments may
+  be optional.
+
+Marker arguments may be strings, ints, bools, or slices thereof.  Strings,
+ints, and bools follow their Go syntax:
+
+```go
+// +kubebuilder:validation:ExclusiveMaximum=false
+// +kubebulder:validation:Format="date-time"
+// +kubebuilder:validation:Maxium=42
+```
+
+For convinience, in simple cases the quotes may be omitted from strings,
+although this is not encouraged for anything other than single-word
+strings:
+
+```go
+// +kubebuilder:validation:Type=string
+```
+
+Slices may be specified either by surrounding them with curly braces and
+separating with commas:
+
+```go
+// +kubebuilder:webhooks:Enum={"crackers, Gromit, we forgot the crackers!","not even wensleydale?"}
+```
+
+or, in simple cases, by separating with semicolons:
+
+```go
+// +kubebuilder:validation:Enum=Wallace;Gromit;Chicken
+```

docs/book/src/reference/markers/crd-validation.md

@@ -0,0 +1,7 @@
+# CRD Validation
+
+These markers modify how the CRD validation schema is produced for the
+types and fields they modify.  Each corresponds roughly to an OpenAPI/JSON
+schema option.
+
+{{#markerdocs CRD validation}}

docs/book/src/reference/markers/crd.md

@@ -0,0 +1,7 @@
+# CRD Generation
+
+These markers describe how to construct a custom resource definition from
+a series of Go types and packages.  Generation of the actual validation
+schema is described by the [validation markers](./crd-validation.md).
+
+{{#markerdocs CRD}}

docs/book/src/reference/markers/object.md

@@ -0,0 +1,6 @@
+# Object/DeepCopy
+
+These markers control when `DeepCopy` and `runtime.Object` implemention
+methods are generated.
+
+{{#markerdocs object}}

docs/book/src/reference/markers/rbac.md

@@ -0,0 +1,9 @@
+# RBAC
+
+These markers cause an [RBAC
+ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole)
+to be generated.  This allows you to describe the permissions that your
+controller requires alongside the code that makes use of those
+permissions.
+
+{{#markerdocs RBAC}}

docs/book/src/reference/markers/webhook.md

@@ -0,0 +1,7 @@
+# Webhook
+
+These markers describe how [webhook configuration](/TODO.md) is generated.
+Use these to keep the description of your webhooks close to the code that
+implements them.
+
+{{#markerdocs Webhook}}