Add / Update GitBook *Test* and *Docs* chapters

cmd/kubebuilder/main.go

@@ -108,12 +108,10 @@ More options:
 
 - run tests
   kubebuilder generate
-  export TEST_ASSET_KUBECTL=/usr/local/kubebuilder/bin/kubectl
-  export TEST_ASSET_KUBE_APISERVER=/usr/local/kubebuilder/bin/kube-apiserver
-  export TEST_ASSET_ETCD=/usr/local/kubebuilder/bin/etcd
   go test ./pkg/...
 
 - build reference documentation to docs/reference/build/index.html
+  kubebuilder create example --group <group> --version <version> --kind <Kind>
   kubebuilder docs
 `,
 	Example: `# Initialize your project

docs/book/SUMMARY.md

@@ -14,6 +14,7 @@
 * Development Workflow
   * [Project Creation and Structure](basics/project_creation_and_structure.md)
   * [Running Tests](basics/running_tests.md)
+  * [Generating API Documentation](basics/generating_documentation.md)
 * Resource Fundamentals
   * [What is a Resource](basics/what_is_a_resource.md)
   * [Simple Resource Example](basics/simple_resource.md)

docs/book/basics/generating_documentation.md

@@ -0,0 +1,106 @@
+{% panel style="info", title="Under Development" %}
+This book is being actively developed.
+{% endpanel %}
+
+# Generating API Documentation
+
+Kubebuilder will generate API reference documentation for your APIs with `kubebuilder docs`.  The
+reference documentation will be built under `docs/reference/build/index.html` and can be opened
+directly in a web browser.
+
+- Use `--docs-copyright` to set the copyright footer
+- Use `--title` to set the title
+
+{% panel style="info", title="Non-Kubebuilder Projects" %}
+Kubebuilder can also be used to generate API reference documentation for non-kubebuilder projects, as long as the
+resources are annotated with `// +kubebuilder:resource` the same as they are in kubebuilder projects.
+{% endpanel %}
+
+## Creating Examples
+
+Users can provide resource examples by running
+`kubebuilder create example --kind <kind> --group <group> --version <version> `.  This will create an example
+file under `docs/reference/kind/kind.yaml` for the user to edit.  The contents of this file will appear
+next to the API reference documentation after rerunning `kubebuilder docs`.
+
+- `note:` description that will appear directly above the example
+- `sample:` example yaml that will be displayed
+
+## Editing Overview and API Group Documentation
+
+Users can modify documentation of the overview and API *groups* by editing the files under
+`docs/reference/static_includes`.
+
+- Edit `_overview.md` to provide documentation for the full set of APIs.
+- Edit `_<group>.md` to provide documentation for a specific API group.
+
+## Customizing the API documentation
+
+The generated documentation is controller by the `docs/reference/config.yaml` file generated by kubebuilder.  This
+file may be manually changed by users to customize the appearance of the documentation.
+
+{% panel style="warning", title="Modifying config.yaml" %}
+When manually modifying config.yaml, users must run `kubebuilder docs` with `--generate-config=false` to
+prevent the file from being rewritten.
+{% endpanel %}
+
+#### Table of Contents
+
+{% method %}
+
+`docs/reference/config.yaml` is automatically generated to create a section for each API group including
+the APIs in the group, and to show the most mature versions of each API.  Both the API sections and
+displayed API versions may be manually controlled.
+
+{% sample lang="yaml" %}
+> generated config.yaml for `kubebuilder create resource --kind Bee --group insect --version v1beta1`
+
+```yaml
+example_location: "examples"
+api_groups: 
+  - "Insect"
+resource_categories: 
+- name: "Insect"
+  include: "insect"
+  resources: 
+  - name: "Bee"
+    version: "v1beta1"
+    group: "insect"
+```
+{% endmethod %}
+
+#### Adding Notes and Warnings to APIs
+
+{% method %}
+
+- Add a note to include more information about a particular resource by providing html in a `description_note:`.
+- Add a warning about a particular resource by providing html in a `description_warning:`.
+- Inline field definitions beneath the Resource (the same way they are done for Spec and Status) by adding a
+  `inline_definitions:` section.
+  - `name:` the display name of the Section
+  - `match:` the naming pattern of fields to inline, where `${resource}` is the name of the resource.
+
+{% sample lang="yaml" %}
+> modified config.yaml for `kubebuilder create resource --kind Bee --group insect --version v1beta1`
+
+```yaml
+example_location: "examples"
+api_groups: 
+  - "Insect"
+inline_definitions:
+  - name: Something
+    match: ${resource}Something
+resource_categories: 
+- name: "Insect"
+  include: "insect"
+  resources: 
+  - name: "Bee"
+    version: "v1beta1"
+    group: "insect"
+    description_note: "More information <a href=\"link to info\">here</a>"
+    description_warning: "Warning about this.  <a href=\"link to info\">More information.</a>"
+```
+{% endmethod %}
+
+
+

docs/book/basics/running_tests.md

@@ -4,33 +4,52 @@ This book is being actively developed.
 
 # Running tests
 
-Kubebuilder `kubebuilder create resource` will create scaffolding tests for controllers and resources
-along side the controller and resource code.  When run, these tests will start a local control plane
-as part of the integration test.  Developers may talk to the local control plane using the provided
-config.
+Kubebuilder will create scaffolding tests for controllers and resources.  When run, these tests will start
+a local control plane as part of the integration test.  Developers may talk to the local control plane
+using the provided config.
+
+#### Resource Tests
+
+The resource tests are created under `pkg/apis/<group>/<version>/<kind>_types_test.go`.  When a resource
+is created with `kubebuilder create resource`, a test file will be created to store and read back the object.
+
+Update the test to include validation you add to your resource.
+
+#### Controller Tests
+
+The controller tests are created under `pkg/controller/<kind>/controller_test.go`.  When a resource
+is created with `kubebuilder create resource`, a test file will be created to start the controller
+and reconcile objects.  The default test will create a new object and verify that the controller
+Reconcile function is called.
+
+Update the test to verify the business logic of your controller.
 
 {% method %}
-## Setup Environment Variables
+## Run the tests
 
-First export the environment variables so the test harness can locate the control plane binaries.
-The control plane binaries are included with kubebuilder.
+Run the tests using `go test`.
 
 {% sample lang="shell" %}
 ```bash
-export TEST_ASSET_KUBECTL=/usr/local/kubebuilder/bin/kubectl
-export TEST_ASSET_KUBE_APISERVER=/usr/local/kubebuilder/bin/kube-apiserver
-export TEST_ASSET_ETCD=/usr/local/kubebuilder/bin/etcd
+go test ./pkg/...
 ```
 {% endmethod %}
 
+
 {% method %}
-## Run the tests
+## Optional: Change Control Plane Test Binaries
 
-Next run the tests as normal.
+To override the test binaries used to start the control plane, set the `TEST_ASSET_` environment variables.
+This can be useful for performing testing against multiple Kubernetes cluster versions.
+
+If these environment variables are unset, kubebuiler will default to the binaries packaged with kubebuilder.
 
 {% sample lang="shell" %}
 ```bash
-go test ./pkg/...
+export TEST_ASSET_KUBECTL=/usr/local/kubebuilder/bin/kubectl
+export TEST_ASSET_KUBE_APISERVER=/usr/local/kubebuilder/bin/kube-apiserver
+export TEST_ASSET_ETCD=/usr/local/kubebuilder/bin/etcd
 ```
 {% endmethod %}
 
+