Generating API Documentation

Kubebuilder will generate API reference documentation for your APIs with kubebuilder docs. Thereference documentation will be built under docs/reference/build/index.html and can be openeddirectly in a web browser.

  • Use —docs-copyright to set the copyright footer
  • Use —title to set the title

Non-Kubebuilder Projects

Kubebuilder can also be used to generate API reference documentation for non-kubebuilder projects, as long as theresources are annotated with // +kubebuilder:resource:path=<resource-name> the same as they are in kubebuilderprojects.

Important: The // +kubebuilder:resource annotation must appear directly above the go structdefining the resource. No blank lines may appear between the annotation and the go struct.

Creating Examples

Users can provide resource examples by runningkubebuilder create example —kind <kind> —group <group> —version <version>. This will create an examplefile under docs/reference/examples/<kind>/<kind>.yaml for the user to edit. The contents of this file will appearnext 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

$ kubebuilder create example —kind Frigate —version v1beta1 —group ships

  1. # docs/reference/examples/frigate/frigate.yaml
  2. note: frigate example
  3. sample: |
  4.   apiVersion: v1beta1
  5.   kind: frigate
  6.   metadata:
  7.     name: frigate
  8.   spec:
  9.     todo: "write me"

Editing Overview and API Group Documentation

Users can modify documentation of the overview and API groups by editing the files underdocs/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.

Adding Notes and Warnings for APIs

It is possible to add notes and warnings to APIs in the reference documentation by annotatingthe go struct with // +kubebuilder:doc:note= or // +kubebuilder:doc:warning=. These willshow up in blue and orange boxes.

  1. // Frigate API documentation goes here.
  2. // +kubebuilder:doc:note=this is a note
  3. // +kubebuilder:doc:warning=this is a warning
  4. // +k8s:openapi-gen=true
  5. // +kubebuilder:resource:path=frigates
  6. type Frigate struct {
  7.     metav1.TypeMeta   `json:",inline"`
  8.     metav1.ObjectMeta `json:"metadata,omitempty"`
  10.     // Spec field documentation goes here.
  11.     Spec   FrigateSpec   `json:"spec,omitempty"`
  13.     // Status field documentation goes here.
  14.     Status FrigateStatus `json:"status,omitempty"`
  15. }

Customizing the API documentation

The generated documentation is controller by the docs/reference/config.yaml file generated by kubebuilder. Thisfile may be manually changed by users to customize the appearance of the documentation, however this isdiscouraged as the user will need to manually managed the config going forward.

Modifying config.yaml

When manually modifying config.yaml, users must run kubebuilder docs with —generate-config=false toprevent the file from being rewritten.

Table of Contents

docs/reference/config.yaml is automatically generated to create a section for each API group includingthe APIs in the group, and to show the most mature versions of each API. Both the API sections anddisplayed API versions may be manually controlled if needed.

generated config.yaml for kubebuilder create resource —kind Bee —group insect —version v1beta1

  1. example_location: "examples"
  2. api_groups: 
  3.   - "Ship"
  4. resource_categories: 
  5. - name: "Ship"
  6.   include: "ship"
  7.   resources: 
  8.   - name: "Frigate"
  9.     version: "v1beta1"
  10.     group: "ship"
  11.     description_warning: "test warnings message annotations"
  12.     description_note: "test notes message annotations"