Documentation for Real Time Collaboration (#10547)

* Update urls page single-mode and two tabs

* Add new doc page for rtc on users section

* Extend documents section with shared models

* Added documentation for sharing the link

* Update docs/source/extension/documents.rst

Co-authored-by: Steven Silvester <ssilvester@apple.com>

* Update docs/source/user/rtc.rst

Co-authored-by: Steven Silvester <ssilvester@apple.com>

Co-authored-by: Steven Silvester <ssilvester@apple.com>

docs/source/extension/documents.rst

@@ -18,24 +18,55 @@ is backed by a file stored on disk (i.e. uses Contents API).
 Overview of document architecture
 ---------------------------------
 
-A 'document' in JupyterLab is represented by a model instance implementing the `IModel <../api/interfaces/docregistry.documentregistry.imodel.html>`__ interface. The model interface is intentionally fairly small, and concentrates on representing the data in the document and signaling changes to that data. Each model has an associated `context <../api/interfaces/docregistry.documentregistry.icontext.html>`__ instance as well. The context for a model is the bridge between the internal data of the document, stored in the model, and the file metadata and operations possible on the file, such as save and revert. Since many objects will need both the context and the model, the context contains a reference to the model as its `.model` attribute.
-
-A single file path can have multiple different models (and hence different contexts) representing the file. For example, a notebook can be opened with a notebook model and with a text model. Different models for the same file path do not directly communicate with each other.
-
-`Document widgets <../api/classes/docregistry.documentregistry-1.html>`__ represent a view of a document model. There can be multiple document widgets associated with a single document model, and they naturally stay in sync with each other since they are views on the same underlying data model.
-
-
-The `Document
-Registry <../api/classes/docregistry.documentregistry-1.html>`__
+A 'document' in JupyterLab is represented by a model instance implementing the
+`IModel <../api/interfaces/docregistry.documentregistry.imodel.html>`__ interface.
+The model interface is intentionally fairly small, and concentrates on representing
+the data in the document and signaling changes to that data. Each model has an
+associated `context <../api/interfaces/docregistry.documentregistry.icontext.html>`__
+instance as well. The context for a model is the bridge between the internal data
+of the document, stored in the model, and the file metadata and operations possible
+on the file, such as save and revert. Since many objects will need both the context
+and the model, the context contains a reference to the model as its `.model` attribute.
+
+A single file path can have multiple different models (and hence different contexts)
+representing the file. For example, a notebook can be opened with a notebook model
+and with a text model. Different models for the same file path do not directly
+communicate with each other.
+
+Models contain an instance of `ModelDB <../api/classes/observables.modeldb-1.html>`__
+that acts as data storage for the model's content. In JupyterLab 3.1, we introduced
+the package ``@jupyterlab/shared-models`` to swap ``ModelDB`` as a data storage
+to make 'documents' collaborative. We implemented these shared models using
+`Yjs <https://yjs.dev>`_, a high-performance CRDT for building collaborative applications
+that automatically sync. You can find all the documentation of Yjs `here <https://docs.yjs.dev>`_.
+At the moment, models contain both a ``ModelDB`` and a ``Shared Model`` instance, so it is
+possible to access ``ModelDB`` yet.
+
+`Document widgets <../api/classes/docregistry.documentregistry-1.html>`__ represent
+a view of a document model. There can be multiple document widgets associated with
+a single document model, and they naturally stay in sync with each other since they
+are views on the same underlying data model.
+
+`Shared Models <../api/interfaces/shared_models.ishareddocument.html>`__ are models
+using Yjs’ shared types as a data structures instead of ``ModelDB``.
+
+The `Document Registry <../api/classes/docregistry.documentregistry-1.html>`__
 is where document types and factories are registered. Plugins can
 require a document registry instance and register their content types
 and providers.
 
-The `Document
-Manager <../api/classes/docmanager.documentmanager-1.html>`__
+The `Document Manager <../api/classes/docmanager.documentmanager-1.html>`__
 uses the Document Registry to create models and widgets for documents.
 The Document Manager handles the lifecycle of documents for the application.
 
+The `Document Provider <../api/classes/docprovider.websocketproviderwithlocks-1.html>`__
+is a WebSocket provider that syncs documents through a new end-point (``api/yjs``)
+in the JupyterLab server. `Providers <https://docs.yjs.dev/ecosystem/connection-provider>`_
+abstract Yjs from the network technology your application uses. They sync Yjs
+documents through a communication protocol or a database. Most providers have
+in common that they use the concept of room names to connect Yjs documents.
+
+
 Document Registry
 -----------------
 
@@ -104,6 +135,24 @@ the Document Manager. Contexts are not meant to be subclassed or
 re-implemented. Instead, the contexts are intended to be the glue
 between the document model and the wider application.
 
+Shared Models
+-------------
+
+The shared-models package contains an `ISharedNotebook
+<../api/interfaces/shared_models.isharednotebook.html>`_ and an `ISharedFile
+<../api/interfaces/shared_models.isharedfile.html>`_ which are the abstract
+interfaces to work against if you want to manipulate a notebook or a file.
+
+These models wrap a `Yjs document (Y.Doc) <https://docs.yjs.dev/api/y.doc>`_ which represents
+a shared document between clients and hold multiple shared objects. They enable you
+to share different `data types like text, Array, Map or set
+<https://docs.yjs.dev/getting-started/working-with-shared-types>`_, to make different
+types of collaborative applications.
+
+In addition, a shared model has an `Awareness <https://docs.yjs.dev/getting-started/adding-awareness>`_
+attribute. This attribute is linked to the *Y.Doc* which means there is one *Awareness* object per document and is
+used for sharing cursor locations and presence information.
+
 Document Manager
 ----------------
 

docs/source/extension/extension_points.rst

@@ -71,6 +71,8 @@ might want to use the services in your extensions.
 - ``@jupyterlab/docmanager:IDocumentManager``: A service for the manager for all
   documents used by the application. Use this if you want to open and close documents,
   create and delete files, and otherwise interact with the file system.
+- ``@jupyterlab/docprovider:IDocumentProviderFactory``: A factory object that creates new providers for
+  shared documents. Use this if you want to create a provider for a new shared document.
 - ``@jupyterlab/documentsearch:ISearchProviderRegistry``: A service for a registry of search
   providers for the application. Plugins can register their UI elements with this registry
   to provide find/replace support.

docs/source/index.rst

@@ -46,6 +46,7 @@ JupyterLab is the next-generation web-based user interface for Project Jupyter.
    user/jupyterhub
    user/export
    user/language
+   user/rtc
    user/directories
 
 .. toctree::

docs/source/user/rtc.rst

@@ -0,0 +1,43 @@
+.. _rtc:
+
+Real Time Collaboration
+=======================
+
+From JupyterLab 3.1, file documents and notebooks have collaborative
+editing using the `Yjs shared editing framework <https://github.com/yjs/yjs>`_.
+Editors are not collaborative by default; to activate it, start JupyterLab
+with the ``--collaborative`` flag.
+
+To share a document with other users, you can copy the URL and send it, or you
+can install a helpful extension called
+`jupyterlab-link-share <https://github.com/jupyterlab-contrib/jupyterlab-link-share>`_
+that might help to share the link including the token.
+
+The new collaborative editing feature enables collaboration in real-time
+between multiple clients without user roles, when sharing the URL of a
+document to other users, they will have access to the same environment you
+are working on (they can write and execute the cells).
+
+Moreover, you can see the cursors from other users with an anonymous
+username, a username that will disappear in a few seconds to make room
+for what is essential, the document's content.
+
+.. image:: images/shared_cursors.png
+   :align: center
+   :class: jp-screenshot
+
+Something you need to be aware of is that not all editors in JupyterLab support sync.
+Additionally, opening the same underlying document using different editor types may result
+in a lack of synchronization.
+For example, on JupyterLab, you can open a Notebook using the Notebook
+editor or a plain text editor, the so-called Editor. Those editors are
+not synchronized because, under the hood, they use a different model to
+represent the document's content, what we call ``DocumentModel``. If you
+modify a Notebook with both editors simultaneously, JupyterLab will prompt
+a warning message indicating that the document's content changed. For more
+information, you can read the section of
+`Documents <https://jupyterlab.readthedocs.io/en/stable/extension/documents.html#documents>`_.
+
+.. image:: images/sync_editors.png
+   :align: center
+   :class: jp-screenshot

docs/source/user/urls.rst

@@ -21,9 +21,6 @@ the nomenclature of the classic notebook; these URLs are ``/tree`` URLs:
 
   http(s)://<server:port>/<lab-location>/lab/tree/path/to/notebook.ipynb
 
-Entering this URL will open the notebook in JupyterLab in
-:ref:`single-document mode <tabs>`.
-
 By default, the file browser will navigate to the directory containing the requested
 file. This behavior can be changed with the optional ``file-browser-path`` query parameter:
 
@@ -62,8 +59,7 @@ multiple users (or browsers) as long as they have access to the same server.
 
 A workspace should only be open in a single browser tab at a time. If JupyterLab
 detects that a workspace is being opened multiple times simultaneously, it will
-prompt for a new workspace name. Opening a document in two different browser
-tabs simultaneously is also not supported.
+prompt for a new workspace name.
 
 .. _url-clone: