Merge pull request #90 from rumpl/feat-move-docs

Move the documentation a bit

Author: rumpl

docs/dev/api/backend.md

@@ -0,0 +1,114 @@
+## Communication with the backend
+
+The `window.ddClient.backend` object can be used to communicate with the backend
+defined in the [vm section](../../extensions/METADATA.md#vm-section) in the
+extensions metadata. The client is already connected to the backend.
+
+It implements the following interface
+
+```typescript
+interface Backend {
+  get(url: string): Promise<unknown>;
+  post(url: string, data: any): Promise<unknown>;
+  put(url: string, data: any): Promise<unknown>;
+  patch(url: string, data: any): Promise<unknown>;
+  delete(url: string): Promise<unknown>;
+  head(url: string): Promise<unknown>;
+  request(config: RequestConfig): Promise<unknown>;
+  execInContainer(container: string, cmd: string): Promise<execResult>;
+  execInVMExtension(cmd: string): Promise<execResult>;
+}
+
+interface RequestConfig {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  data: any;
+}
+
+interface nodeExecResult {
+  readonly cmd?: string;
+  readonly killed?: boolean;
+  readonly signal?: string;
+  readonly code?: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+interface execResult extends nodeExecResult {
+  lines(): string[];
+  parseJsonLines(): any[];
+  parseJsonObject(): any;
+}
+```
+
+Example usages:
+
+```typescript
+window.ddClient.backend
+  .get("/some/service")
+  .then((value: any) => console.log(value));
+
+window.ddClient.backend
+  .post("/some/service", { ... })
+  .then((value: any) => console.log(value));
+
+window.ddClient.backend
+  .put("/some/service", { ... })
+  .then((value: any) => console.log(value));
+
+window.ddClient.backend
+  .patch("/some/service", { ... })
+  .then((value: any) => console.log(value));
+
+window.ddClient.backend
+  .delete("/some/service")
+  .then((value: any) => console.log(value));
+
+window.ddClient.backend
+  .head("/some/service")
+  .then((value: any) => console.log(value));
+
+window.ddClient.backend
+  .request({ url: "/url", method: "GET", headers: { 'header-key': 'header-value' }, data: { ... }})
+  .then((value: any) => console.log(value));
+```
+
+## Running a command in the backend container
+
+If your extensions ships with additional binaries that should be run inside the
+backend container you can use the `execInVMExtension` function
+
+```typescript
+const output = await window.ddClient.backend.execInVMExtension(
+  `cliShippedInTheVm xxx`
+);
+console.log(output);
+```
+
+## Invoking an extension binary
+
+You can run binaries defined in the [host section](../../extensions/METADATA.md#host-section)
+in the exension metadata.
+
+```typescript
+window.ddClient.execHostCmd(`cliShippedOnHost xxx`).then((cmdResult: any) => {
+  console.log(cmdResult);
+});
+```
+
+Invoking an extension binary on your host and getting the output stream:
+
+```typescript
+window.ddClient.spawnHostCmd(
+  `cliShippedOnHost`,
+  [`arg1`, `arg2`],
+  (data: any, err: any) => {
+    console.log(data.stdout, data.stderr);
+    // Once the command exits we get the status code
+    if (data.code) {
+      console.log(data.code);
+    }
+  }
+);
+```

docs/dev/api/dashboard.md

@@ -0,0 +1,24 @@
+## User notifications
+
+Toasts provide a brief notification to the user. They appear temporarily and
+shouldn't interrupt the user experience, they don't require user input to disappear.
+
+```typescript
+window.ddClient.toastError("Something went wrong");
+```
+
+## Opening a URL
+
+This function opens an external URL with the system default browser.
+
+```typescript
+window.ddClient.openExternal("https://docker.com");
+```
+
+_Note:_ the URL must have the protocol `http` or `https`.
+
+## Navigation to Dashboard routes
+
+From your extension, you can navigate to various tabs in Docker Desktop Dashboard.
+
+See details [here](dashboard-routes-navigation.md)

docs/dev/api/docker.md

@@ -0,0 +1,73 @@
+## Docker objects
+
+### Listing containers
+
+```typescript
+const containers = await window.ddClient.listContainers();
+```
+
+This method takes an optional argument in the form of an object:
+
+```json
+{
+  "all": true,
+  "limit": 10,
+  "size": true,
+  "filters": "..."
+}
+```
+
+For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/engine/api/v1.37/#operation/ContainerList)
+
+### Listing images
+
+```typescript
+const images = await window.ddClient.listImages();
+```
+
+This method takes an optional argument in the form of an object:
+
+```json
+{
+  "all": true,
+  "filters": "...",
+  "digests": true
+}
+```
+
+For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/engine/api/v1.37/#tag/Image)
+
+## Docker commands
+
+You can also directly execute the `docker` binary.
+
+```typescript
+const output = await window.ddClient.execDockerCmd("info", "--format", '"{{ json . }}"');
+```
+
+The result will contain both the standard output and the standard error of the
+executed command
+
+```json
+{
+  "stderr": "...",
+  "stdout": "..."
+}
+```
+
+In this example the docker command output is a json output.
+
+For convenience, the command result object also has methods to easily parse it:
+
+- `output.lines(): string[]` split output lines
+- `output.parseJsonObject(): any` parse a well formed json output
+- `output.parseJsonLines(): any[]` parse each output line as a json object
+
+If the output of the command is too long or you need to get the output as a
+stream you can use the `spawnDockerCmd` function:
+
+```typescript
+window.ddClient.spawnDockerCmd("logs", ["-f", "..."], (data, error) => {
+  console.log(data.stdout);
+});
+```