diff --git a/cmd/kubebuilder/main.go b/cmd/kubebuilder/main.go index 16dcc95fe1a..a00fdaed665 100644 --- a/cmd/kubebuilder/main.go +++ b/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 --version --kind kubebuilder docs `, Example: `# Initialize your project diff --git a/docs/book/SUMMARY.md b/docs/book/SUMMARY.md index 359f95205aa..0489dff80e1 100644 --- a/docs/book/SUMMARY.md +++ b/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) diff --git a/docs/book/basics/generating_documentation.md b/docs/book/basics/generating_documentation.md new file mode 100644 index 00000000000..0690fc8b321 --- /dev/null +++ b/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 --group --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 `_.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 here" + description_warning: "Warning about this. More information." +``` +{% endmethod %} + + + diff --git a/docs/book/basics/running_tests.md b/docs/book/basics/running_tests.md index 74fa77bdcbd..bcb282a0af8 100644 --- a/docs/book/basics/running_tests.md +++ b/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///_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//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 %} +