docs: document client API for python/gRPC client

Author: mangelajo

docs/.DS_Store

@@ -0,0 +1,32 @@
+# Client API
+
+This section provides reference documentation for Jumpstarter's client APIs. Covering topics such as:
+
+- Listing exporters
+- Requesting a lease
+- Listing leases
+
+please see the [Client API Reference](reference.md) for more details.
+
+## Listing Exporters
+
+The client library provides a function to list all exporters in the cluster.
+
+```python
+from jumpstarter.config.client import ClientConfigV1Alpha1
+
+client = ClientConfigV1Alpha1.from_file("~/.config/jumpstarter/clients/majopela.yaml")
+response = client.list_exporters(with_leases=True, with_online=True, page_size=1000)
+for exporter in response.exporters:
+    if exporter.online:
+        print(exporter.name)
+        print(exporter.lease)
+
+print("next page token: ", response.next_page_token)
+```
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+reference.md
+```

docs/source/.DS_Store

@@ -0,0 +1,22 @@
+# Client API Reference
+
+## Loading config files
+```{eval-rst}
+.. autoclass:: jumpstarter.config.client.ClientConfigV1Alpha1()
+    :members: from_file, from_env, load, list
+    :exclude-members: __init__
+```
+
+## Manipulating config files
+```{eval-rst}
+.. autoclass:: jumpstarter.config.client.ClientConfigV1Alpha1()
+    :members: save, dump_yaml, list, delete
+    :exclude-members: __init__
+```
+
+## Interact with the service
+```{eval-rst}
+.. autoclass:: jumpstarter.config.client.ClientConfigV1Alpha1()
+    :members: get_exporter, list_exporters, create_lease, delete_lease, lease, list_leases, update_lease
+    :exclude-members: __init__
+```

docs/source/reference/package-apis/client/index.md

@@ -4,6 +4,7 @@ This section provides reference documentation for Jumpstarter's package APIs and
 components. The documentation covers:
 
 - [Drivers](drivers/index.md): APIs for various driver categories
+- [Client API](client/index.md): APIs for the client library: listing exporters, requesting a lease, etc.
 - [Exceptions](exceptions.md): Exceptions raised by driver clients
 
 These references are useful for developers extending Jumpstarter or integrating
@@ -13,5 +14,6 @@ with custom hardware.
 :maxdepth: 1
 :hidden:
 drivers/index.md
+client/index.md
 exceptions.md
 ```

docs/source/reference/package-apis/client/reference.md

@@ -148,6 +148,7 @@ async def get_exporter(
         self,
         name: str,
     ):
+        """Gets an exporter by name."""
         svc = ClientService(channel=await self.channel(), namespace=self.metadata.namespace)
         return await svc.GetExporter(name=name)
 
@@ -161,6 +162,20 @@ async def list_exporters(
         include_leases: bool = False,
         include_online: bool = False,
     ):
+        """Lists exporters.
+
+        Args:
+            * page_size: The number of exporters to return.
+            * page_token: The token to use to get the next page of exporters.
+            * filter: A filter to apply to the list of exporters.
+            * include_leases: Whether to include leases in the response.
+            * include_online: Whether to include online status in the response.
+        Returns:
+            .exporters: list[Exporter]
+            .next_page_token: str | None
+            .include_online: bool : Whether to include online status in the response.
+            .include_leases: bool : Whether to include leases in the response.
+        """
         svc = ClientService(channel=await self.channel(), namespace=self.metadata.namespace)
         exporters_response = await svc.ListExporters(page_size=page_size, page_token=page_token, filter=filter)
 
@@ -202,6 +217,12 @@ async def create_lease(
         duration: timedelta,
         begin_time: datetime | None = None,
     ):
+        """Creates a lease request.
+        Args:
+            selector: The selector to use to create the lease.
+            * duration: The duration of the lease.
+            * begin_time: The beginning time of the lease.
+        """
         svc = ClientService(channel=await self.channel(), namespace=self.metadata.namespace)
         return await svc.CreateLease(
             selector=selector,
@@ -215,6 +236,7 @@ async def delete_lease(
         self,
         name: str,
     ):
+        """Deletes a lease by name."""
         svc = ClientService(channel=await self.channel(), namespace=self.metadata.namespace)
         await svc.DeleteLease(
             name=name,
@@ -229,6 +251,17 @@ async def list_leases(
         filter: str | None = None,
         only_active: bool = True,
     ):
+        """Lists leases.
+
+        Args:
+            * page_size: The number of leases to return.
+            * page_token: The token to use to get the next page of leases.
+            * filter: A filter to apply to the list of leases.
+            * only_active: Whether to only include active leases.
+        Returns:
+            .leases: list[Lease]
+            .next_page_token: str | None
+        """
         svc = ClientService(channel=await self.channel(), namespace=self.metadata.namespace)
         return await svc.ListLeases(
             page_size=page_size,
@@ -245,6 +278,14 @@ async def update_lease(
         duration: timedelta | None = None,
         begin_time: datetime | None = None,
     ):
+        """Updates a lease by name.
+        Can be used to extend the duration of an active lease, or modify the desired begin
+        time and duration of a lease request.
+        Args:
+            * name: The name of the lease to update.
+            * duration: The duration of the lease.
+            * begin_time: The beginning time of the lease.
+        """
         svc = ClientService(channel=await self.channel(), namespace=self.metadata.namespace)
         return await svc.UpdateLease(name=name, duration=duration, begin_time=begin_time)
 
@@ -290,6 +331,7 @@ async def lease_async(
 
     @classmethod
     def from_file(cls, path: os.PathLike):
+        """Loads a client config from a file path."""
         with open(path) as f:
             v = cls.model_validate(yaml.safe_load(f))
             v.alias = os.path.basename(path).split(".")[0]
@@ -310,6 +352,7 @@ def try_from_env(cls):
 
     @classmethod
     def from_env(cls):
+        """Loads a client config from the environment variables."""
         return cls()
 
     @classmethod
@@ -341,6 +384,7 @@ def save(cls, config: Self, path: Optional[os.PathLike] = None) -> Path:
 
     @classmethod
     def dump_yaml(cls, config: Self) -> str:
+        """Dumps a client config as YAML."""
         return yaml.safe_dump(config.model_dump(mode="json", exclude={"path", "alias"}), sort_keys=False)
 
     @classmethod