Merge pull request #875 from DirectXMan12/docs/autogen-marker-docs

📖 Marker Docs

docs/book/book.toml

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

docs/book/install-and-build.sh

@@ -1,11 +1,54 @@
 #!/bin/bash
 
+set -e
+
 os=$(go env GOOS)
 arch=$(go env GOARCH)
 
+# translate arch to rust's conventions (if we can)
+if [[ ${arch} == "amd64" ]]; then
+    arch="x86_64"
+elif [[ ${arch} == "x86" ]]; then
+    arch="i686"
+fi
+
+# translate os to rust's conventions (if we can)
+ext="tar.gz"
+cmd="tar -C /tmp -xzvf"
+case ${os} in
+    windows)
+        target="pc-windows-msvc"
+        ext="zip"
+        cmd="unzip -d /tmp"
+        ;;
+    darwin)
+        target="apple-darwin"
+        ;;
+    linux)
+        # works for linux, too
+        target="unknown-${os}-gnu"
+        ;;
+    *)
+        target="unknown-${os}"
+        ;;
+esac
+
 # grab mdbook
-# mdbook's deploy got borked by a CI move, so grab our build till that gets
-# fixed (https://github.com/rust-lang-nursery/mdBook/issues/904).
-curl -sL -o /tmp/mdbook https://storage.googleapis.com/kubebuilder-build-tools/mdbook-0.2.3-${os}-${arch}
+# we hardcode linux/amd64 since rust uses a different naming scheme and it's a pain to tran
+echo "downloading mdBook-v0.3.1-${arch}-${target}.${ext}"
+set -x
+curl -sL -o /tmp/mdbook.${ext} https://github.com/rust-lang-nursery/mdBook/releases/download/v0.3.1/mdBook-v0.3.1-${arch}-${target}.${ext}
+${cmd} /tmp/mdbook.${ext}
 chmod +x /tmp/mdbook
+
+echo "grabbing the latest released controller-gen"
+# TODO(directxman12): remove the @v0.2.0-beta.4 once get v0.2.0 released,
+# so that we actually get the latest version
+go get sigs.k8s.io/controller-tools/cmd/controller-gen@v0.2.0-beta.4
+
+# make sure we add the go bin directory to our path
+gobin=$(go env GOBIN)
+gobin=${GOBIN:-$(go env GOPATH)/bin}  # GOBIN won't always be set :-/
+
+export PATH=${gobin}:$PATH
 /tmp/mdbook build

docs/book/litgo.sh

@@ -4,7 +4,7 @@ set -ex
 
 (
     pushd ./utils
-    go build -o ../../../bin/literate-go ./literate.go
+    go build -o ../../../bin/literate-go ./litgo
     popd
 ) &>/dev/null
 

docs/book/markerdocs.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+set -ex
+
+(
+    pushd ./utils
+    go build -o ../../../bin/marker-docs ./markerdocs
+    popd
+) &>/dev/null
+
+../../bin/marker-docs "$@"

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/cronjob-tutorial/epilogue.md

@@ -3,5 +3,4 @@
 Things left to do:
 
 - Write custom printer columns
-- Discuss webhooks
 - Use different watches

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

@@ -44,9 +44,10 @@ type CronJobReconciler struct {
 }
 
 /*
-Most controllers eventually end up running on the cluster, so they need RBAC permissions.
-These are the bare minimum permissions needed to run.  As we add more functionality, we'll
-need to revisit these.
+Most controllers eventually end up running on the cluster, so they need RBAC
+permissions, which we specify using controller-tools [RBAC
+markers](/reference/markers/rbac.md).  These are the bare minimum permissions
+needed to run.  As we add more functionality, we'll need to revisit these.
 */
 
 // +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=get;list;watch;create;update;patch;delete

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

@@ -58,9 +58,11 @@ At this point, our main function is fairly simple:
 
 - We set up some basic flags for metrics.
 
-- We instantiate a [*manager*](../TODO.md), which keeps track of running all of
-our controllers, as well as setting up shared caches and clients to the API
-server (notice we tell the manager about our Scheme).
+- We instantiate a
+[*manager*](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/manager#Manager),
+which keeps track of running all of our controllers, as well as setting up
+shared caches and clients to the API server (notice we tell the manager about
+our Scheme).
 
 - We run our manager, which in turn runs all of our controllers and webhooks.
 The manager is set up to run until it receives a graceful shutdown signal.

docs/book/src/cronjob-tutorial/testdata/project/api/v1/cronjob_webhook.go

@@ -50,9 +50,9 @@ func (r *CronJob) SetupWebhookWithManager(mgr ctrl.Manager) error {
 
 /*
 Notice that we use kubebuilder markers to generate webhook manifests.
-This markers is responsible for generating a mutating webhook manifest.
+This marker is responsible for generating a mutating webhook manifest.
 
-The meaning of each marker can be found [here](../TODO.md).
+The meaning of each marker can be found [here](/reference/markers/webhook.md).
 */
 
 // +kubebuilder:webhook:path=/mutate-batch-tutorial-kubebuilder-io-v1-cronjob,mutating=true,failurePolicy=fail,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v1,name=mcronjob.kb.io
@@ -87,10 +87,7 @@ func (r *CronJob) Default() {
 }
 
 /*
-Notice that we use kubebuilder markers to generate webhook manifests.
-This markers is responsible for generating a validating webhook manifest.
-
-The meaning of each marker can be found [here](../TODO.md).
+This marker is responsible for generating a validating webhook manifest.
 */
 
 // +kubebuilder:webhook:path=/validate-batch-tutorial-kubebuilder-io-v1-cronjob,mutating=false,failurePolicy=fail,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v1,name=vcronjob.kb.io
@@ -156,7 +153,7 @@ You can find kubebuilder validation markers (prefixed
 with `// +kubebuilder:validation`) in the [API](api-design.md)
 You can find all of the kubebuilder supported markers for
 declaring validation by running `controller-gen crd -w`,
-or [here](../TODO.md).
+or [here](/reference/markers/crd-validation.md).
 */
 
 func (r *CronJob) validateCronJobSpec() *field.Error {

docs/book/src/cronjob-tutorial/testdata/project/controllers/cronjob_controller.go

@@ -87,7 +87,8 @@ func ignoreNotFound(err error) error {
 
 /*
 Notice that we need a few more RBAC permissions -- since we're creating and
-managing jobs now, we'll need permissions for those.
+managing jobs now, we'll need permissions for those, which means adding
+a couple more [markers](/reference/markers/rbac.md).
 */
 
 // +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=get;list;watch;create;update;patch;delete

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

@@ -154,7 +154,7 @@ Let's take a quick look at the `api/v1/disk_webhook.go` file.
 
 If you look at `main.go`, you will notice the following snippet that invokes the
 SetupWebhook method.
-```Go
+```go
 	.....
 
 	if err = (&infrav1.Disk{}).SetupWebhookWithManager(mgr); err != nil {
@@ -176,7 +176,14 @@ CRD_OPTIONS ?= "crd:trivialVersions=false"
 ```
 
 Run `make manifests` to ensure that CRD manifests gets generated under `config/crd/bases/` directory.
-[TODO](../TODO.md) embed a compressed form of the generated CRD `testdata/project/config/crd`
+
+<details><summary>`infra.kubebuilder.io_disks.yaml`: the generated CRD YAML</summary>
+
+```yaml
+{{#include ./testdata/project/config/crd/bases/infra.kubebuilder.io_disks.yaml}}
+```
+
+</details>
 
 ### Manifests Generation
 

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

@@ -34,7 +34,7 @@ kubectl get disks.v2.infra.kubebuilder.io/disk-sample -o yaml
 ```
 
 ```yaml
-apiVersion: infra.kubebuilder.io/v2 <-- note the v2 version
+apiVersion: infra.kubebuilder.io/v2 # <-- note the v2 version
 kind: Disk
 metadata:
   name: disk-sample
@@ -54,15 +54,15 @@ status: {}
 kubectl get disks.v3.infra.kubebuilder.io/disk-sample -o yaml
 ```
 ```yaml
-apiVersion: infra.kubebuilder.io/v3 <-- note the v3 version
+apiVersion: infra.kubebuilder.io/v3 # <-- note the v3 version
 kind: Disk
 metadata:
   name: disk-sample
   selfLink: /apis/infra.kubebuilder.io/v3/namespaces/default/disks/disk-sample
   uid: 0e9be0fd-a284-11e9-bbbe-42010a8001af <-- note the same uid as v2
   ....
 spec:
-  pricePerGB: <-- note the pricePerGB name of the field
+  pricePerGB: # <-- note the pricePerGB name of the field
     amount: 10
     currency: USD
 status: {}