Add docs for generating docs

Author: pwittrock

README.md

@@ -30,10 +30,16 @@ kubebuilder init --domain example.com
 
 # Create a new API and controller
 kubebuilder create resource --group bar --version v1alpha1  --kind Foo
+kubectl apply -f hack/sample/foo.yaml
 
 # Install and run your API into the cluster for your current kubeconfig context
 GOBIN=$(pwd)/bin go install <PROJECT_PACKAGE>/cmd/controller-manager
 bin/controller-manager --kubeconfig ~/.kube/config
+kubectl apply -f hack/sample/foo.yaml
+
+# Build your documentation
+kubebuilder create example --group bar --version v1alpha1 --kind Foo
+kubebuilder docs
 ```
 
 See the [user guide](docs/tools_user_guide.md) for more details

docs/creating_reference_documentation.md

@@ -0,0 +1,23 @@
+# Building reference documentation
+
+## Build reference documentation
+
+You may build Kubernetes style reference documentation for your APIs to `docs/reference/build/index.html` by
+running `kubebuilder docs`.
+
+**Note:** There is currently an issue where building docs does not work if multiple versions of APIs for the
+same group are defined.
+
+## Create an example for your API
+
+You may create an example that will be included in the reference documentation by running the following command
+and editing the newly created file:
+
+```sh
+kubebuilder create example --group <group> --version <version> --kind <kind>
+```
+
+## Add overview or API group documentation
+
+You may add information about the API groups or creating an overview by editing the .md files
+under `docs/reference/static_includes`.

docs/tools_user_guide.md

@@ -166,3 +166,18 @@ export CONTROLLER_IMAGE=<controller-image>
 kubectl run $NAME --serviceaccount=installer --image=$INSTALL_IMAGE --restart=OnFailure -- ./installer \
   --controller-image=$CONTROLLER_IMAGE --name=$NAME
 ```
+
+## Build docs for your APIs
+
+It will be helpful for your users to have API documentation.  You can generate Kubernetes style APIs using
+kubebuilder:
+
+```sh
+# Create and edit an example for each API
+kubebuilder create example --group group --version version --kind kind
+
+# Generate the docs to docs/reference/build/index.html
+kubebuilder docs
+```
+
+For more information see [creating reference documentation](creating_reference_documentation.md)