Enhance SDK documenation

docs/authentication.md

@@ -4,7 +4,7 @@ Authenticating with your cluster allows you to perform actions such as creating
 
 ## Method 1 Token Authentication
 This is how a typical user would authenticate to their cluster using `TokenAuthentication`.
-```
+``` python
 from codeflare_sdk import TokenAuthentication
 
 auth = TokenAuthentication(
@@ -26,7 +26,7 @@ If the user has not specifically authenticated through the SDK by other means su
 ## Method 3 Specifying a Kubernetes Config File
 A user can specify a config file via a different authentication class `KubeConfigFileAuthentication` for authenticating with the SDK.<br>
 This is what loading a custom config file would typically look like.
-```
+``` python
 from codeflare_sdk import KubeConfigFileAuthentication
 
 auth = KubeConfigFileAuthentication(

docs/cluster-configuration.md

@@ -31,9 +31,40 @@ The `labels={"exampleLabel": "example"}` parameter can be used to apply addition
 
 After creating their `cluster`, a user can call `cluster.up()` and `cluster.down()` to respectively create or remove the Ray Cluster.
 
+## Parameters of the `ClusterConfiguration`
+Below is a table explaining each of the `ClusterConfiguration` parameters and their default values.
+| Name | Type | Description | Default |
+| :--------- | :-------- | :-------- | :-------- |
+| `name` | `str` | The name of the Ray Cluster/AppWrapper | Required - No default |
+| `namespace` | `Optional[str]` | The namespace of the Ray Cluster/AppWrapper | `None` |
+| `head_cpu_requests` | `Union[int, str]` | CPU resource requests for the Head Node | `2` |
+| `head_cpu_limits` | `Union[int, str]` | CPU resource limits for the Head Node | `2` |
+| `head_memory_requests` | `Union[int, str]` | Memory resource requests for the Head Node | `8` |
+| `head_memory_limits` | `Union[int, str]` | Memory limits for the Head Node | `8` |
+| `head_extended_resource_requests` | `Dict[str, Union[str, int]]` | Extended resource requests for the Head Node see example above | `{}` |
+| `worker_cpu_requests` | `Union[int, str]` | CPU resource requests for the Worker Node | `1` |
+| `worker_cpu_limits` | `Union[int, str]` | CPU resource limits for the Worker Node | `1` |
+| `num_workers` | `int` | Number of Worker Nodes for the Ray Cluster | `1` |
+| `worker_memory_requests` | `Union[int, str]` | Memory resource requests for the Worker Node | `8` |
+| `worker_memory_limits` | `Union[int, str]` | Memory resource limits for the Worker Node | `8` |
+| `appwrapper` | `bool` | A boolean that wraps the Ray Cluster in an AppWrapper when set to True | `False` |
+| `envs` | `Dict[str, str]` | A dictionary of environment variables to set for the Ray Cluster | `{}` |
+| `image` | `str` | A paramater for specifying the Ray Image | `""` |
+| `image_pull_secrets` | `List[str]` | A Parameter for providing a list of Image Pull Secrets | `[]` |
+| `write_to_file` | `bool` | A boolean for writing the Ray Cluster as a Yaml file if set to True | `False` |
+| `verify_tls` | `bool` | A boolean indicating whether to verify TLS when connecting to the cluster | `True` |
+| `labels` | `Dict[str, str]` | A dictionary of labels to apply to the cluster | `{}` |
+| `worker_extended_resource_requests` | `Dict[str, Union[str, int]]` | Extended resource requests for the Worker Node see example above | `{}` |
+| `extended_resource_mapping` | `Dict[str, str]` | A dictionary of custom resource mappings to map extended resource requests to RayCluster resource names | `{}` |
+| `overwrite_default_resource_mapping` | `bool` | A boolean indicating whether to overwrite the default resource mapping | `False` |
+| `local_queue` | `Optional[str]` | A parameter for specifying the Local Queue label for the Ray Cluster | `None` |
+
+
+
+
 
 ## Deprecating Parameters
-The following parameters of the `ClusterConfiguration` are being deprecated in release `v0.22.0`. <!-- TODO: When removing deprecated parameters update this statement -->
+The following parameters of the `ClusterConfiguration` are being deprecated.
 | Deprecated Parameter | Replaced By |
 | :--------- | :-------- |
 | `head_cpus` | `head_cpu_requests`, `head_cpu_limits` |

docs/ray-cluster-interaction.md

@@ -0,0 +1,67 @@
+# Ray Cluster Interaction
+
+The CodeFlare SDK offers multiple ways to interact with Ray Clusters including the below methods.
+
+## get_cluster()
+The `get_cluster()` function is used to initialise a `Cluster` object from a pre-existing Ray Cluster/AppWrapper. <br>
+Below is an example of it's usage:
+``` python
+from codeflare_sdk import get_cluster
+cluster = get_cluster(cluster_name="raytest", namespace="example", is_appwrapper=False, write_to_file=False)
+-> output: Yaml resources loaded for raytest
+cluster.status()
+-> output:
+                    🚀 CodeFlare Cluster Status 🚀
+ ╭─────────────────────────────────────────────────────────────────╮
+ │   Name                                                          │
+ │   raytest                                           Active ✅   │
+ │                                                                 │
+ │   URI: ray://raytest-head-svc.example.svc:10001                 │
+ │                                                                 │
+ │   Dashboard🔗                                                   │
+ │                                                                 │
+ ╰─────────────────────────────────────────────────────────────────╯
+(<CodeFlareClusterStatus.READY: 1>, True)
+cluster.down()
+cluster.up() # This function will create an exact copy of the retrieved Ray Cluster only if the Ray Cluster has been previously deleted.
+```
+
+These are the parameters the `get_cluster()` function accepts:
+* `cluster_name: str # Required` -> The name of the Ray Cluster.
+* `namespace: str # Default: "default"` -> The namespace of the Ray Cluster.
+* `is_appwrapper: bool # Default: False` -> When set to `True` the function will attempt to retrieve an AppWrapper instead of a Ray Cluster.
+* `write_to_file: bool # Default: False` -> When set to `True` the Ray Cluster/AppWrapper will be written to a file similar to how it is done in `ClusterConfiguration`.
+
+## list_all_queued()
+The `list_all_queued()` function returns (and prints by default) a list of all currently queued-up Ray Clusters in a given namespace.
+It accepts the following parameters:
+* `namespace: str # Required` -> The namespace you want to retrieve the list from.
+* `print_to_console: bool # Default: True` -> Allows the user to print the list to their console.
+* `appwrapper: bool # Default: False` -> When set to `True` allows the user to list queued AppWrappers.
+
+
+
+## list_all_clusters()
+The `list_all_clusters()` function will return a list of detailed descriptions of Ray Clusters to the console by default. It accepts the following parameters:
+* `namespace: str # Required` -> The namespace you want to retrieve the list from.
+* `print_to_console: bool # Default: True` -> A boolean that allows the user to print the list to their console.
+
+> [!NOTE]
+> The following methods require a `Cluster` object to be initialised see [Cluster Configuration](./cluster-configuration.md)
+
+## cluster.up()
+The `cluster.up()` function creates a Ray Cluster in the given namespace.
+
+## cluster.down()
+The `cluster.down()` function deletes the Ray Cluster in the given namespace.
+
+## cluster.status()
+The `cluster.status()` function prints out the status of the Ray Cluster's state with a link to the Ray Dashboard.
+
+## cluster.details()
+The `cluster.details()` function prints out a detailed description of the Ray Cluster's status, worker resources and a link to the Ray Dashboard.
+
+## cluster.wait_ready()
+The `cluster.wait_ready()` function waits for the requested cluster to be ready, up to an optional timeout and checks every 5 seconds. It accepts the following parameters:
+* `timeout: Optional[int] # Default: None` -> Allows the user to define a timeout for the `wait_ready()` function.
+* `dashboard_check: bool # Default: True` -> If enabled the `wait_ready()` function will wait until the Ray Dashboard is ready too.

docs/ui-widgets.md

@@ -0,0 +1,29 @@
+# Jupyter UI Widgets
+Below are some examples of the Jupyter UI Widgets that are included in the CodeFlare SDK. <br>
+> [!NOTE]
+> To use the widgets functionality you must be using the CodeFlare SDK in a Jupyter Notebook environment.
+
+## Cluster Up/Down Buttons
+The Cluster Up/Down buttons appear after successfully initialising your [ClusterConfiguration](cluster-configuration.md#ray-cluster-configuration).
+There are two buttons and a checkbox `Cluster Up`, `Cluster Down` and `Wait for Cluster?` which mimic the [cluster.up()](ray-cluster-interaction.md#clusterup), [cluster.down()](ray-cluster-interaction.md#clusterdown) and [cluster.wait_ready()](ray-cluster-interaction.md#clusterwait_ready) functionality.
+
+After initialising their `ClusterConfiguration` a user can select the `Wait for Cluster?` checkbox then click the `Cluster Up` button to create their Ray Cluster and wait until it is ready. The cluster can be deleted by clicking the `Cluster Down` button.<br>
+
+<img title="ui buttons" alt="An image of the up/down ui buttons" src="images/ui-buttons.png">
+
+## View Clusters UI Table
+The View Clusters UI Table allows a user to see a list of Ray Clusters with information on their configuration including number of workers, CPU requests and limits along with the clusters status.
+
+<img title="view clusters" alt="An image of the view clusters ui table" src="images/ui-view-clusters.png">
+
+Above is a list of two Ray Clusters `raytest` and `raytest2` each of those headings is clickable and will update the table to view the selected Cluster's information.
+There are three buttons under the table `Cluster Down`, `View Jobs` and `Open Ray Dashboard`.<br>
+* The `Cluster Down` button will delete the selected Cluster.
+* The `View Jobs` button will try to open the Ray Dashboard's Jobs view in a Web Browser. The link will also be printed to the console.
+* The `Open Ray Dashboard` button will try to open the Ray Dashboard view in a Web Browser. The link will also be printed to the console.
+
+The UI Table can be viewed by calling the following function.
+``` python
+from codeflare_sdk import view_clusters
+view_clusters() # Accepts namespace parameter but will try to gather the namespace from the current context
+```