New Book

This introduces a new version of the book.  The initial portion is built
around a tutorial building the cronjob controller.

It now uses [mdbook](https://crates.io/crates/mdbook), which is like
gitbook but maintained and written in rust.

We've got a custom "plugin" (executable) that slurps Go files into
book pages for parts of the tutorial (look for `{{#literatego
./path/to/thing}}`).

Author: DirectXMan12

.gitignore

@@ -1,7 +1,7 @@
 .idea/
 
-# Not check in node_modules to a specific arch and os.
-docs/book/node_modules/
+# don't check in the build output of the book
+docs/book/book/
 
 # Editor temp files
 *~

build/thirdparty/brodocs/Dockerfile

@@ -0,0 +1,12 @@
+[book]
+authors = ["The Kubebuilder Maintainers"]
+multilingual = false
+src = "src"
+title = "The Kubebuilder Book"
+
+[output.html]
+google-analytics = "UA-119864590-1"
+curly-quotes = true
+
+[preprocessor.literatego]
+command = "./litgo.sh"

build/thirdparty/brodocs/runbrodocs.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+os=$(go env GOOS)
+arch=$(go env GOARCH)
+
+# 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}
+chmod +x /tmp/mdbook
+/tmp/mdbook build

docs/book/book.json

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

docs/book/book.toml

@@ -0,0 +1,29 @@
+# Summary
+
+[Introduction](./introduction.md)
+
+[Quick Start](./quick-start.md)
+
+---
+
+- [Tutorial: Building CronJob](./cronjob-tutorial.md)
+
+  - [What's in a basic project?](./cronjob-tutorial/basic-project.md)
+  - [Every journey needs a start, every program a main](./cronjob-tutorial/empty-main.md)
+  - [Groups and Versions and Kinds, oh my!](./cronjob-tutorial/gvks.md)
+  - [Adding a new API](./cronjob-tutorial/new-api.md)
+  - [Designing an API](./cronjob-tutorial/api-design.md)
+
+      - [A Brief Aside: What's the rest of this stuff?](./cronjob-tutorial/other-api-files.md)
+
+  - [What's in a controller?](./cronjob-tutorial/controller-overview.md)
+  - [Implementing a controller](./cronjob-tutorial/controller-implementation.md)
+
+      - [You said something about main?](./cronjob-tutorial/main-revisited.md)
+
+  - [Running and deploying the controller](./cronjob-tutorial/running.md)
+  - [Epilogue](./cronjob-tutorial/epilogue.md)
+
+---
+
+[Appendix: The TODO Landing Page](./TODO.md)

docs/book/install-and-build.sh

@@ -0,0 +1,7 @@
+# TODO
+
+If you're seeing this page, it's probably because something's not done in
+the book yet.  Go [see if anyone else has found
+this](https://github.com/kubernetes-sigs/kubebuilder/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Fdocumentation)
+or [bug the
+maintainers](https://github.com/kubernetes-sigs/kubebuilder/issues/new?assignees=&labels=kind%2Fdocumentation).

docs/book/litgo.sh

@@ -0,0 +1,36 @@
+# Tutorial: Building CronJob
+
+Too many tutorials start out with some really contrived setup, or some toy
+application that gets the basics across, and then stalls out on the more
+complicated suff.  Instead, this tutorial should take you through (almost)
+the full gamut of complexity with Kubebuilder, starting off simple and
+building up to something pretty full-featured.
+
+Let's pretend (and sure, this is a teensy bit contrived) that we've
+finally gotten tired of the maintenance burden of the non-Kubebuilder
+implementation of the CronJob controller in Kuberntes, and we'd like to
+rewrite it using KubeBuilder.
+
+The job (no pun intended) of the *CronJob* controller is to run one-off
+tasks on the Kubernetes cluster at regular intervals.  It does the by
+bulding on top of the *Job* controller, whose task is to run one-off tasks
+once, seeing them to completion.
+
+Instead of trying to tackle rewriting the Job controller as well, we'll
+use this as an opportunity to see how to interact with external types.
+
+## Scaffolding Out Our Project
+
+As covered in the [quick start](./quick-start.md), we'll need to scaffold
+out a new project.  Make sure you've [installed
+Kubebuilder](./quick-start.md#installation), then scaffold out a new
+project:
+
+```bash
+# we'll use a domain of tutorial.kubebuilder.io,
+# so all API groups will be <group>.tutorial.kubebuilder.io.
+kubebuilder init --domain tutorial.kubebuilder.io
+```
+
+Now that we've got've a project in place, let's take a look at what
+Kubebuilder has scaffolded for us so far...