[Feature] [documentation] Autogenerate CR docs

[DmitriGekhtman]

Search before asking

• [X] I had searched in the issues and found no similar feature requirement.

Description

Docs for KubeRay CRs should be auto-generated and added to an API reference section in the KubeRay documentation.

I wonder if KubeBuilder itself includes some functionality to do this kind of auto-generation?

Use case

Document functionality fully without having to link to the actual source of truth (go structs).

Related issues

No response

Are you willing to submit a PR?

• [ ] Yes I am willing to submit a PR!

[DmitriGekhtman]

cc @cadedaniel

[rudeigerc]

I have tried elastic/crd-ref-docs to generate API documentation of CRD with other Kubernetes Operator projects and it works well. Here is an example of generated docs with KubeRay using crd-ref-docs.

However since the main part of KubeRay documentation seems to be hosted on Ray documentation currently, I am not sure where to place the generated references.

/cc @cadedaniel @kevin85421

---

API Reference

Packages

• ray.io/v1alpha1

ray.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the ray v1alpha1 API group

Resource Types

• RayCluster
• RayJob
• RayService

AppStatus

Appears in:

• RayServiceStatus

Field	Description
message string
lastUpdateTime Time
healthLastUpdateTime Time	Keep track of how long the service is healthy. Update when Serve deployment is healthy or first time convert to unhealthy from healthy.
serveDeploymentStatuses object (keys:string, values:ServeDeploymentStatus)

AutoscalerOptions

AutoscalerOptions specifies optional configuration for the Ray autoscaler.

Appears in:

• RayClusterSpec

Field	Description
resources ResourceRequirements	Resources specifies optional resource request and limit overrides for the autoscaler container. Default values: 500m CPU request and limit. 512Mi memory request and limit.
image string	Image optionally overrides the autoscaler's container image. This override is for provided for autoscaler testing and development.
imagePullPolicy PullPolicy	ImagePullPolicy optionally overrides the autoscaler container's image pull policy. This override is for provided for autoscaler testing and development.
env EnvVar array	Optional list of environment variables to set in the autoscaler container.
envFrom EnvFromSource array	Optional list of sources to populate environment variables in the autoscaler container.
volumeMounts VolumeMount array	Optional list of volumeMounts. This is needed for enabling TLS for the autoscaler container.
securityContext SecurityContext	SecurityContext defines the security options the container should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
idleTimeoutSeconds integer	IdleTimeoutSeconds is the number of seconds to wait before scaling down a worker pod which is not using Ray resources. Defaults to 60 (one minute). It is not read by the KubeRay operator but by the Ray autoscaler.
upscalingMode UpscalingMode	UpscalingMode is "Conservative", "Default", or "Aggressive." Conservative: Upscaling is rate-limited; the number of pending worker pods is at most the size of the Ray cluster. Default: Upscaling is not rate-limited. Aggressive: An alias for Default; upscaling is not rate-limited. It is not read by the KubeRay operator but by the Ray autoscaler.

---

[rudeigerc]

I have noticed that there is an API Reference field in the Ray documentation, maybe it's a good choice. But you will have to sync the documentation when releasing KubeRay since it is in the seperated repository. WDYT?

/cc @cadedaniel @kevin85421

[kevin85421]

Thanks, @rudeigerc!

I have noticed that there is an API Reference field in the Ray documentation, maybe it's a good choice.

I would prefer to add a link in the Ray repository that directs to the API reference in the KubeRay repository. By the way, I plan to upgrade the CRD version shortly. Would it be acceptable to create the API reference after I upgrade the CRD version?

[rudeigerc]

Sounds good to me :) Sure. I'm happy to submit a PR after that.