fix: added usages guide with examples to options reference #388

[aashvgit]

What this PR does / why we need it:
Adds a comprehensive usage guide to the Options Reference page, and added an example how to pass options to TrainerClient.train().
Which issue(s) this PR fixes
#388

Fixes #
Added introduction explaining the 'options' parameter
--Added per-option usage examples ('Name', 'Labels', 'Annotations',
'TrainerCommand', 'TrainerArgs', 'RuntimePatch')
--Added a "Combining Multiple Options" example

• Added a .. note:: about backend compatibility

Checklist:
.

[google-oss-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign electronic-waste for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[github-actions]

🎉 Welcome to the Kubeflow SDK! 🎉

Thanks for opening your first PR! We're happy to have you as part of our community 🚀

Here's what happens next:

• If you haven't already, please check out our Contributing Guide for repo-specific guidelines and the Kubeflow Contributor Guide for general community standards
• Our team will review your PR soon! cc @kubeflow/kubeflow-sdk-team

Join the community:

• Slack: Join our #kubeflow-ml-experience and #kubeflow-trainer Slack channels
• Meetings: Attend the Kubeflow SDK and ML Experience bi-weekly meetings

Feel free to ask questions in the comments if you need any help or clarification!
Thanks again for contributing to Kubeflow! 🙏

[Copilot]

Pull request overview

Adds a usage guide to the Trainer “Options Reference” documentation to help users understand how to pass options into TrainerClient.train() and apply common options.

Changes:

• Added an introductory explanation and a basic options=[...] example for TrainerClient.train().
• Added per-option sections (e.g., Name/Labels/Annotations) plus a “Combining Multiple Options” example.
• Added a backend-compatibility note and kept the existing API reference (autoclass) list.

[Copilot]

This code sample also uses fuc= instead of func= for CustomTrainer, which makes it invalid if copied; update the keyword argument to func.

[Copilot]

This code sample also uses fuc= instead of func= for CustomTrainer, which makes it invalid if copied; update the keyword argument to func.

[Copilot]

This code sample also uses fuc= instead of func= for CustomTrainer, which makes it invalid if copied; update the keyword argument to func.

[Copilot]

The “TrainerCommand” section text says it overrides .spec.trainer.command and only works with CustomTrainerContainer, but the example below shows a RuntimePatch applied to a CustomTrainer; either update the example to demonstrate TrainerCommand with CustomTrainerContainer or move/rename this section to document RuntimePatch instead.

[Copilot]

Inline code formatting and class name are off here: use Sphinx inline-literal markup (CustomTrainerContainer, CustomTrainer, BuiltinTrainer) and fix the typo “BuildinTrainer” → “BuiltinTrainer”.

Suggested change

	Override the trainer container command "spec.trainer.command". It can only be used with ''CustomTrainerContainer'' not with ''CustomTrainer'' or ''BuildinTrainer''.
	Override the trainer container command ``spec.trainer.command``. It can only be used with ``CustomTrainerContainer`` not with ``CustomTrainer`` or ``BuiltinTrainer``.

[Copilot]

This example uses CustomTrainer but never imports it, so the snippet won’t run if copied; import CustomTrainer (e.g., from kubeflow.trainer or kubeflow.trainer.types) or adjust the example to only use imported symbols.

[Copilot]

Typo in the note: “uusupported” should be “unsupported”.

Suggested change

	Not all options work with every backend, each option documents which backend it supports. An uusupported option will raise an "ValueError" during the runtime.
	Not all options work with every backend, each option documents which backend it supports. An unsupported option will raise a "ValueError" during runtime.

[Copilot]

Grammar in the note is incorrect (“an ValueError”); change to “a ValueError” (and consider dropping the extra quotes around ValueError).

Suggested change

	Not all options work with every backend, each option documents which backend it supports. An uusupported option will raise an "ValueError" during the runtime.
	Not all options work with every backend, each option documents which backend it supports. An unsupported option will raise a ValueError at runtime.

[Copilot]

This example again uses CustomTrainer(fuc=...) (should be func), which will fail if copied; update the keyword argument to func.

[Copilot]

CustomTrainer takes a func parameter (not fuc), so this code sample would raise TypeError if used as written; update the keyword argument to func.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 7 comments.

[Copilot]

The Annotations description is missing a space before the inline literal ("metadata(metadata.annotations)"); add the space so the text renders/readably parses as "metadata (metadata.annotations)".

Suggested change

	Add annotations to the TrainJob resource metadata(``metadata.annotations``). Only supported on the Kubernetes backend.
	Add annotations to the TrainJob resource metadata (``metadata.annotations``). Only supported on the Kubernetes backend.

[Copilot]

The TrainerCommand restrictions line uses incorrect reST markup (''...'' and mismatched quotes) and inconsistent capitalization ("Can Only"); use consistent inline-literal/class markup (e.g., CustomTrainerContainer, CustomTrainer, BuiltinTrainer) and "can only".

Suggested change

	Can Only be used with ''CustomTrainerContainer'' not with ''CustomTrainer''' or ''BuiltinTrainer''.
	Can only be used with ``CustomTrainerContainer`` and not with ``CustomTrainer`` or ``BuiltinTrainer``.

[Copilot]

The TrainerArgs section is inaccurate: the option overrides .spec.trainer.args and is only valid with CustomTrainerContainer on the Kubernetes backend (per the implementation), but the text implies it appends args generically.

Suggested change

	Append extra arguments to the trainer container command.
	.. code-block:: python
	from kubeflow.trainer import TrainerClient, CustomTrainer
	from kubeflow.trainer.options import TrainerArgs
	trainer_client = TrainerClient()
	job_id = trainer_client.train(
	trainer=CustomTrainer(func=train_function),
	Override the trainer container arguments (``spec.trainer.args``). Only supported on the **Kubernetes backend** with ``CustomTrainerContainer``.
	.. code-block:: python
	from kubeflow.trainer import TrainerClient, CustomTrainerContainer
	from kubeflow.trainer.options import TrainerArgs
	trainer_client = TrainerClient()
	job_id = trainer_client.train(
	trainer=CustomTrainerContainer(image="my-image:latest"),

[Copilot]

The TrainerArgs example uses CustomTrainer (func-based), but TrainerArgs raises ValueError unless the trainer is a CustomTrainerContainer; update the example to use CustomTrainerContainer (and show args consistent with that).

Suggested change

	from kubeflow.trainer import TrainerClient, CustomTrainer
	from kubeflow.trainer.options import TrainerArgs
	trainer_client = TrainerClient()
	job_id = trainer_client.train(
	trainer=CustomTrainer(func=train_function),
	from kubeflow.trainer import TrainerClient, CustomTrainerContainer
	from kubeflow.trainer.options import TrainerArgs
	trainer_client = TrainerClient()
	job_id = trainer_client.train(
	trainer=CustomTrainerContainer(image="my-image:latest"),

[Copilot]

The RuntimePatch description runs two sentences together and uses inconsistent quoting (''Kubernetes backend''); add a period after the spec.runtimePatches clause and use consistent markup (e.g., Kubernetes backend or KubernetesBackend).

Suggested change

	Apply structured patches to the TrainJob (``spec.runtimePatches``) Use this for advanced Kubernetes-level customisation such as adding init containers, volumes, or tolerations. Only supported on the ''Kubernetes backend''.
	Apply structured patches to the TrainJob (``spec.runtimePatches``). Use this for advanced Kubernetes-level customisation such as adding init containers, volumes, or tolerations. Only supported on the **Kubernetes backend**.

[Copilot]

There should be a blank line between the paragraph ending with the :py:meth: role and the .. code-block:: directive; without it Sphinx can emit an "Explicit markup" warning and render incorrectly.

Suggested change

	:py:meth:`kubeflow.trainer.TrainerClient.train` method.
	:py:meth:`kubeflow.trainer.TrainerClient.train` method.

[Copilot]

ValueError is currently written with single backticks; in this doc it should be marked as code or a Python class reference (e.g., ValueError or :class:ValueError) to avoid mis-rendering.

Suggested change

	`ValueError` at runtime.
	``ValueError`` at runtime.