Added donkey export decription

WebReflection · WebReflection · commit f16f9174607b · 2024-10-04T17:42:39.000+02:00
diff --git a/docs/api.md b/docs/api.md
@@ -417,6 +417,33 @@ store = await storage("my-data-store", storage_class=MyStorage)
 # The store object is now an instance of MyStorage.
 ```
 
+### `@pyscript/core/donkey`
+
+Meant as *JS* related imports, you can `import { donkey } from '@pyscript/core/dist/core.js'` and automatically have both *pyscript* module running on your page and a utility to bootstrap a terminal based worker that could evaluate any Python code you need to.
+
+```js title="A donkey worker"
+import { donkey } from '@pyscript/core/dist/core.js';
+
+const {
+  process,              // process(code) directly (code visible on the terminal)
+  execute,              // execute(statement) in Python exec way
+  evaluate,             // evaluate(expression) in Python eval way
+  clear,                // clear() the terminal
+  reset,                // reset() the terminal (including colors)
+  kill,                 // kill() the worker forever
+} = donkey({
+  type: 'py' || 'mpy',  // the donkey interpreter to run
+  persistent: false,    // use `true` to track globals and locals
+  terminal: '',         // optionally set a target terminal container
+  config: {},           // the worker config (packages, files, etc.)
+});
+```
+
+About the **terminal** option, please note by default *PyScript* would create a target for that, so that if you don't want it visible on your page you can point to a *CSS* addressable container that is not visible (that is: a `#target` element that has a `display: none` as *CSS* property).
+
+With this primitive, and without even bothering with specialized *PyScript* tags, we hope anyone can try out of the box what is that *PyScript* enables on the Web!
+
+
 ### `@pyscript/core/dist/storage.js`
 
 The equivalent functionality based on the *JS* module can be found through our module.
