From cccf9bf3e221aa031f77e5e54fb751e250bdf73b Mon Sep 17 00:00:00 2001 From: Phillip Wittrock Date: Tue, 20 Mar 2018 23:36:57 -0700 Subject: [PATCH] Add docs for generating docs --- README.md | 6 ++++++ docs/creating_reference_documentation.md | 23 +++++++++++++++++++++++ docs/tools_user_guide.md | 15 +++++++++++++++ 3 files changed, 44 insertions(+) create mode 100644 docs/creating_reference_documentation.md diff --git a/README.md b/README.md index 539546b473..8585655cb8 100644 --- a/README.md +++ b/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 /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 diff --git a/docs/creating_reference_documentation.md b/docs/creating_reference_documentation.md new file mode 100644 index 0000000000..82c80fae22 --- /dev/null +++ b/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 --version --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`. \ No newline at end of file diff --git a/docs/tools_user_guide.md b/docs/tools_user_guide.md index 43b20e0bd8..81e99d4f33 100644 --- a/docs/tools_user_guide.md +++ b/docs/tools_user_guide.md @@ -166,3 +166,18 @@ export 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) \ No newline at end of file