Merge pull request #121 from gtardif/docs_stream_lines

Update documentation about exec streaming, mention splitOutputLines and add docker events sample

Author: gtardif

docs/dev/api/backend.md

@@ -1,6 +1,6 @@
 ## Communication with the extension backend
 
-The `window.ddClient.extension.vm` object can be used to communicate with the backend defined in the [vm section](../../extensions/METADATA.md#vm-section) in the extensions metadata.
+The `ddClient.extension.vm` object can be used to communicate with the backend defined in the [vm section](../../extensions/METADATA.md#vm-section) in the extensions metadata.
 
 ### get
 
@@ -9,7 +9,7 @@ The `window.ddClient.extension.vm` object can be used to communicate with the ba
 Performs an HTTP GET request to a backend service.
 
 ```typescript
-window.ddClient.extension.vm.service
+ddClient.extension.vm.service
  .get("/some/service")
  .then((value: any) => console.log(value)
 ```
@@ -65,23 +65,27 @@ Executes a command in the backend container.
 Example: Execute the command `ls -l` inside the **backend container**:
 
 ```typescript
-await window.ddClient.extension.vm.cli.exec("ls", ["-l"]);
+await ddClient.extension.vm.cli.exec("ls", ["-l"]);
 ```
 
 Streams the output of the command executed in the backend container.
 
 Example: Spawn the command `ls -l` inside the **backend container**:
 
 ```typescript linenums="1"
-await window.ddClient.extension.vm.cli.exec("ls", ["-l"], {
+await ddClient.extension.vm.cli.exec("ls", ["-l"], {
   stream: {
-    onOutput(data: { stdout: string } | { stderr: string }): void {
-      console.error(data.stdout);
+    onOutput(data) {
+      if (data.stdout) {
+        console.error(data.stdout);
+      } else {
+        console.log(data.stderr);
+      }
     },
-    onError(error: any): void {
+    onError(error) {
       console.error(error);
     },
-    onClose(exitCode: number): void {
+    onClose(exitCode) {
       console.log("onClose with exit code " + exitCode);
     },
   },
@@ -114,16 +118,20 @@ in the exension metadata.
 Example: Execute the shipped binary `kubectl -h` command in the **host**:
 
 ```typescript
-await window.ddClient.extension.host.cli.exec("kubectl", ["-h"]);
+await ddClient.extension.host.cli.exec("kubectl", ["-h"]);
 ```
 
 Example: Provided the `kubectl` binary is shipped as part of your extension, you can spawn the `kubectl -h` command in the **host** and get the output stream:
 
 ```typescript linenums="1"
-await window.ddClient.extension.host.cli.exec("kubectl", ["-h"], {
+await ddClient.extension.host.cli.exec("kubectl", ["-h"], {
   stream: {
     onOutput(data: { stdout: string } | { stderr: string }): void {
-      console.error(data.stdout);
+      if (data.stdout) {
+        console.error(data.stdout);
+      } else {
+        console.log(data.stderr);
+      }
     },
     onError(error: any): void {
       console.error(error);

docs/dev/api/dashboard-routes-navigation.md

@@ -1,11 +1,11 @@
 # Dashboard Routes Navigation
 
-`window.ddClient.desktopUI.navigation` allow to navigate to specific screens of the Docker Desktop Dashboard like containers view, images view, a specific container logs, a specific image details, volumes, dev environments.
+`ddClient.desktopUI.navigation` allow to navigate to specific screens of the Docker Desktop Dashboard like containers view, images view, a specific container logs, a specific image details, volumes, dev environments.
 
 Example: navigate to a given container logs
 
 ```typescript
-await window.ddClient.desktopUI.navigation.viewContainerLogs(id);
+await ddClient.desktopUI.navigation.viewContainerLogs(id);
 ```
 
 #### Parameters

docs/dev/api/dashboard.md

@@ -10,7 +10,7 @@ shouldn't interrupt the user experience, they don't require user input to disapp
 Display a toast message of type success.
 
 ```typescript
-window.ddClient.desktopUI.toast.success("message");
+ddClient.desktopUI.toast.success("message");
 ```
 
 ### warning
@@ -20,7 +20,7 @@ window.ddClient.desktopUI.toast.success("message");
 Display a toast message of type warning.
 
 ```typescript
-window.ddClient.desktopUI.toast.warning("message");
+ddClient.desktopUI.toast.warning("message");
 ```
 
 ### error
@@ -30,7 +30,7 @@ window.ddClient.desktopUI.toast.warning("message");
 Display a toast message of type error.
 
 ```typescript
-window.ddClient.desktopUI.toast.error("message");
+ddClient.desktopUI.toast.error("message");
 ```
 
 More details about method parameters and return types are available in the [Toast API reference](reference/interfaces/Toast.md).
@@ -56,7 +56,7 @@ This function opens an external URL with the system default browser.
 Opens an external URL with the system default browser.
 
 ```typescript
-window.ddClient.host.openExternal("https://docker.com");
+ddClient.host.openExternal("https://docker.com");
 ```
 
 !!! note

docs/dev/api/docker.md

@@ -5,15 +5,15 @@
 Get the list of containers
 
 ```typescript
-const containers = await window.ddClient.docker.listContainers();
+const containers = await ddClient.docker.listContainers();
 ```
 
 ▸ **listImages**(`options?`): `Promise`<`unknown`\>
 
 Get the list of local container images
 
 ```typescript
-const images = await window.ddClient.docker.listImages();
+const images = await ddClient.docker.listImages();
 ```
 
 Use the [Docker API reference](reference/interfaces/Docker.md) for details about these methods
@@ -37,7 +37,7 @@ Extensions can also directly execute the `docker` command line.
 ▸ **exec**(`cmd`, `args`): `Promise`<[`ExecResult`](reference/interfaces/ExecResult.md)\>
 
 ```typescript
-const result = await window.ddClient.docker.cli.exec("info", [
+const result = await ddClient.docker.cli.exec("info", [
   "--format",
   '"{{ json . }}"',
 ]);
@@ -65,21 +65,51 @@ Streams the output as a result of the execution of a docker command.
 Useful when you need to get the output as a stream or the output of the command is too long.
 
 ```typescript linenums="1"
-await window.ddClient.docker.cli.exec("logs", ["-f", "..."], {
+await ddClient.docker.cli.exec("logs", ["-f", "..."], {
   stream: {
-    onOutput(data: { stdout: string } | { stderr: string }): void {
-      console.log(data.stdout);
+    onOutput(data) {
+      if (data.stdout) {
+        console.error(data.stdout);
+      } else {
+        console.log(data.stderr);
+      }
     },
-    onError(error: any): void {
+    onError(error) {
       console.error(error);
     },
-    onClose(exitCode: number): void {
+    onClose(exitCode) {
       console.log("onClose with exit code " + exitCode);
     },
+    splitOutputLines: true,
   },
 });
 ```
 
+This can also be useful to listen to docker events:
+
+```typescript linenums="1"
+await ddClient.docker.cli.exec(
+  "events",
+  ["--format", "{{ json . }}", "--filter", "container=my-container"],
+  {
+    stream: {
+      onOutput(data) {
+        if (data.stdout) {
+          const event = JSON.parse(data.stdout);
+          console.log(event);
+        } else {
+          console.log(data.stderr);
+        }
+      },
+      onClose(exitCode) {
+        console.log("onClose with exit code " + exitCode);
+      },
+      splitOutputLines: true,
+    },
+  }
+);
+```
+
 Use the [Exec API reference](reference/interfaces/Exec.md) for details about these methods
 
 ### Deprecated execution of Docker commands

docs/dev/api/overview.md

@@ -6,6 +6,21 @@ electron or nodejs APIs.
 The extension UI API provides a way for the frontend to perform different actions
 and communicate with the Docker Desktop dashboard or the underlying system.
 
+JavaScript API libraries are available (with Typescript support) in order to get all the API definition in your extension code.
+
+- [@docker/extension-api-client](https://www.npmjs.com/package/@docker/extension-api-client) gives access to the extension API entrypoint `DockerDesktopCLient`
+- [@docker/extension-api-client-types](https://www.npmjs.com/package/@docker/extension-api-client-types) can be added as a dev dependency in order to get types auto-completion in your IDE.
+
+```Typescript
+import { createDockerDesktopClient } from '@docker/extension-api-client';
+
+export function App() {
+  //obtain Docker Desktop client
+  const ddClient = createDockerDesktopClient();
+```
+
+The `ddClient` object gives access to various APIs, organized in different categories:
+
 - [Extension Backend](./backend.md)
 - [Docker](./docker.md)
 - [Dashboard](./dashboard.md)