docs: Add docstrings for StudioClient functions

PHS-616

src/documentation/how_tos/how_to_run_the_trace_viewer.ipynb

@@ -4,25 +4,46 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Running the Trace Viewer\n",
+    "# How to use PhariaStudio for Debugging in a SaaS Configuration\n",
+    "<div class=\"alert alert-info\">  \n",
     "\n",
-    "Make sure you have your access to the Jfrog instance at https://alephalpha.jfrog.io. \n",
-    "Then login to the container registry with docker with your JFrog user name and a JFrog token as the password with the following command:\n",
+    "Make sure your account has permissions to use the PhariaStudio application.\n",
     "\n",
-    "```bash\n",
-    "docker login alephalpha.jfrog.io\n",
-    "```\n",
-    "\n",
-    "Note: If you do not already have a JFrog token, you can find it on the website under the \"Set me up\" option, either in the resource of interest or under your profile name.\n",
-    "\n",
-    "Afterwards, run the container locally to start the trace viewer:\n",
+    "For an on-prem or local installation, please contact the PhariaStudio team.\n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "\n",
-    "```bash\n",
-    "docker run -p 3000:3000 alephalpha.jfrog.io/container-images/trace-viewer:latest\n",
-    "```\n",
+    "0. Generate a trace of your `Task` of interest.\n",
+    "1. Initialize a `StudioClient` with a project.\n",
+    "    - Use an existing project or create a new one with the `StudioClient.create_project` function.\n",
+    "2. Submit your traces with the client\n",
+    "    - submit a single trace via  `Tracer.export_for_viewing` and `StudioClient.submit_trace`\n",
+    "    - [Recommended] submit multiple traces via `StudioClient.submit_from_tracer`. \n",
+    "3. Click the link \n",
     "\n",
-    "Finally, visit `http://localhost:3000`, where you can upload a trace to interact with the data."
+    "### Example"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {

src/intelligence_layer/connectors/studio/studio.py

@@ -112,6 +112,17 @@ def _get_project(self, project: str) -> int | None:
             return None
 
     def create_project(self, project: str, description: Optional[str] = None) -> int:
+        """Creates a project in PhariaStudio.
+
+        Projects are uniquely identified by the user provided name.
+
+        Args:
+            project: User provided name of the project.
+            description: Description explaining the usage of the project. Defaults to None.
+
+        Returns:
+            The ID of the newly created project.
+        """
         url = urljoin(self.url, "/api/projects")
         data = StudioProject(name=project, description=description)
         response = requests.post(
@@ -127,11 +138,30 @@ def create_project(self, project: str, description: Optional[str] = None) -> int
         return int(response.text)
 
     def submit_trace(self, data: Sequence[ExportedSpan]) -> str:
+        """Sends the provided spans to Studio as a singular trace.
+
+        The method fails if the span list is empty, has already been created or if
+        spans belong to multiple traces.
+
+        Args:
+            data: Spans to create the trace from. Created by exporting from a `Tracer`.
+
+        Returns:
+            The ID of the created trace.
+        """
         if len(data) == 0:
             raise ValueError("Tried to upload an empty trace")
         return self._upload_trace(ExportedSpanList(data))
 
     def submit_from_tracer(self, tracer: Tracer) -> list[str]:
+        """Sends all trace data from the Tracer to Studio.
+
+        Args:
+            tracer: Tracer to extract data from.
+
+        Returns:
+            List of created trace IDs.
+        """
         traces = defaultdict(list)
         for span in tracer.export_for_viewing():
             traces[span.context.trace_id].append(span)