Add some documentation about integrating jupyterlab-collaborative-chat

docs/source/developers/contributing/index.md

@@ -1,6 +1,6 @@
 # Contributing
 
-This project is part of *jupyterlab* organization.
+This project is included in *jupyterlab* organization.
 
 Before contributing to it, please read the [jupyter contributing guide](https://docs.jupyter.org/en/latest/contributing/content-contributor.html).
 

docs/source/developers/contributing/jupyterlab-collaborative-chat.md

@@ -1,4 +1,4 @@
-# jupyterlab-collaborative-chat
+# Collaborative chat
 
 The `jupyterlab-collaborative-chat` extension adds collaborative chats to jupyterlab.
 

docs/source/developers/contributing/jupyterlab-ws-chat.md

@@ -1,4 +1,4 @@
-# jupyterlab-collaborative-chat
+# Websocket chat
 
 The `jupyterlab-ws-chat` extension adds a chat panel relying on websocket for messaging.
 

docs/source/developers/developing_extensions/extension-providing-chat.md

@@ -303,6 +303,8 @@ const myChatExtension: JupyterFrontEndPlugin<void> = {
 };
 ```
 
+(autocompletion-registry)=
+
 ### autocompletionRegistry
 
 The `autocompletionRegistry` adds autocompletion feature to the chat input. This can be

docs/source/developers/developing_extensions/index.md

@@ -2,14 +2,14 @@
 
 Other extensions can depends on one or the other of the packages.
 
-This section describe how an extension can provide a chat, and how an extension can
-extend the features of a chat extension.
+This section describe how an extension can provide a chat, and how to make use of one
+of the chat extensions in another extension.
 
 ```{toctree}
 ---
 maxdepth: 2
 ---
 
 ./extension-providing-chat
-./extending-extension
+./using-chat-extensions
 ```

docs/source/developers/developing_extensions/using-chat-extensions.md

@@ -0,0 +1,152 @@
+# Using a chat extension in another extension
+
+## Collaborative chat
+
+The collaborative chat depends on [jupyter collaboration](https://jupyterlab-realtime-collaboration.readthedocs.io/en/latest/index.html)
+to exchange the messages.
+
+As a very brief summary, jupyter collaboration allows jupyterlab users to share a
+document in real time, based on [CRDT](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type).
+All changes made to the document are propagated to all users. These change can occur
+from the frontend or from the backend. The shared document has an object representation
+in Typescript (for the frontend) and in Python (for the backend). These representation
+can be accessed and used by external extensions.
+
+### Exposed token
+
+`jupyterlab-collaborative-chat` expose several token that allow external extension to
+interact with.
+
+#### IChatFactory
+
+This token is composed of:
+
+- `widgetConfig` object, to retrieve and change the current [settings](#chat-settings)
+of all the chats
+- `tracker`, a widget tracker that allow to track all the collaborative chats, and to
+get the current one.
+
+```{caution}
+Currently the widget tracker only track the main area widgets, not the one opened in the
+side panel.
+```
+
+#### IChatPanel
+
+This token is a pointer to the left panel containing chats.\
+It can be useful to programmatically open chat in the panel for example, or to list the
+opened chats.
+
+#### IAutocompletionRegistry
+
+this is the [autocompletion registry](#autocompletion-registry) used by the chat widgets.
+
+Autocompletion commands can be added to it, and than usable from the chat widget.
+
+### Interact with the chat from the backend
+
+`jupyter_collaboration` provides a websocket server to handle every shared document
+server side. This server can be used in an extension to retrieve a shared document.
+
+In addition, when a shared document is created, an event is emitted. We can use that
+event data to trigger a connection to the shared document.
+
+Below is an example of an server extension that respond every message written to any
+collaborative chat:
+
+```python
+import jupyter_collaboration
+import time
+import uuid
+from functools import partial
+from jupyter_collaboration.utils import JUPYTER_COLLABORATION_EVENTS_URI
+from jupyter_events import EventLogger
+from jupyter_server.extension.application import ExtensionApp
+from pycrdt import ArrayEvent
+
+from .ychat import YChat
+
+
+if int(jupyter_collaboration.__version__[0]) >= 3:
+    COLLAB_VERSION = 3
+else:
+    COLLAB_VERSION = 2
+
+BOT = {
+    "username": str(uuid.uuid4()),
+    "name": "user",
+    "display_name": "User"
+}
+
+
+class MyExtension(ExtensionApp):
+    name = "my_extension"
+    app_name = "My Extension"
+    description = """
+    this extension interact with collaborative chats
+    """
+
+    def initialize(self):
+        super().initialize()
+        self.event_logger = self.serverapp.web_app.settings["event_logger"]
+        self.event_logger.add_listener(
+            schema_id=JUPYTER_COLLABORATION_EVENTS_URI,
+            listener=self.connect_chat
+        )
+
+    async def connect_chat(self, logger: EventLogger, schema_id: str, data: dict) -> None:
+        if data["room"].startswith("text:chat:") \
+            and data["action"] == "initialize"\
+            and data["msg"] == "Room initialized":
+
+            self.log.info(f"Collaborative chat server is listening for {data["room"]}")
+            chat = await self.get_chat(data["room"])
+            callback = partial(self.on_change, chat)
+            chat.ymessages.observe(callback)
+
+    async def get_chat(self, room_id: str) -> YChat:
+        if COLLAB_VERSION == 3:
+            collaboration = self.serverapp.web_app.settings["jupyter_server_ydoc"]
+            document = await collaboration.get_document(
+                room_id=room_id,
+                copy=False
+            )
+        else:
+            collaboration = self.serverapp.web_app.settings["jupyter_collaboration"]
+            server = collaboration.ywebsocket_server
+
+            room = await server.get_room(room_id)
+            document = room._document
+        return document
+
+    def on_change(self, chat: YChat, events: ArrayEvent) -> None:
+        for change in events.delta:
+            if not "insert" in change.keys():
+                continue
+            messages = change["insert"]
+            for message in messages:
+                if message["sender"] == BOT["username"] or message["raw_time"]:
+                    continue
+                chat.create_task(
+                    self.write_message(
+                        chat,
+                        f"Received:\n\n- **id**: *{message["id"]}*:\n\n- **body**: *{message["body"]}*")
+                )
+
+    async def write_message(self, chat: YChat, body: str) -> None:
+        bot = chat.get_user_by_name(BOT["name"])
+        if not bot:
+            chat.set_user(BOT)
+        else:
+            BOT["username"] = bot["username"]
+
+        chat.add_message({
+            "type": "msg",
+            "body": body,
+            "id": str(uuid.uuid4()),
+            "time": time.time(),
+            "sender": BOT["username"],
+            "raw_time": False
+        })
+
+```

docs/source/developers/index.md

@@ -2,7 +2,7 @@
 
 This section is addressed to developers, and contains documentation about:
 
-- how to develop an extension providing a chat or extending a chat extension
+- how to develop an extension providing a chat or to include a chat extension
 - how to contribute to this project
 
 ```{toctree}

docs/source/users/index.md

@@ -1,6 +1,6 @@
 # Users
 
-## jupyterlab-collaborative-chat
+## Collaborative chat
 
 The `jupyterlab-collaborative-chat` extension adds collaborative chats to jupyterlab.
 
@@ -61,7 +61,7 @@ area, like any other document.
 Opening a chat from the left panel will open it in the left panel.
 ```
 
-## jupyterlab-ws-chat
+## Websocket chat
 
 The `jupyterlab-ws-chat` extension adds a chat panel relying on websocket for messaging.
 
@@ -87,7 +87,7 @@ pip uninstall jupyterlab-ws-chat
 
 The chat can be opened from the left panel ![chat icon](../../../packages/jupyter-chat/style/icons/chat.svg){w=24px}.
 
-## Using the chat
+## Chat usage
 
 The chat UI is composed of a list of messages and an input to send new messages.