Docs (#102)

* Overview

* Schema

* Custom documents

* Improves overview

* Review

* Review

* Review

Author: hbcarlos

docs/source/custom.md

@@ -1,3 +1,20 @@
 # Custom documents
 
-Coming soon!
+Writing an application for a new kind of collaborative document requires the definition of a custom YDoc.
+
+This section will focus on extending documents to use in JupyterLab. In JupyterLab, the front-end conforms to the `ISharedDocument` interface and expects a `YDocument`, both present in the [`@jupyter/ydoc`](./overview.md#jupyter-ydoc) package. In contrast, the back-end conforms to the `YBaseDoc` class in [`jupyter_ydoc`](./overview.md#jupyterydoc).
+
+On a few occasions, we can extend the front-end model and reuse the back-end counterpart without extending it. Extending only the front-end will prevent JupyterLab from saving the new attributes to disk since those new attributes will not be exported by the back-end model when requesting the document's content. This could be the case, for example, when creating a commenting extension where we want to sync the comments through different clients, but we do not want to save them to disk, or at least not within the document.
+
+Once we implement our new models, it is time to export them to be consumed by JupyterLab. In JupyterLab, we register new file types or new document models for existing file types from the front-end. For this reason, the wording that we will use from now on is highly tight to JupyterLab development, and we highly recommend reading JupyterLab's documentation or at least [the section about documents](https://jupyterlab.readthedocs.io/en/stable/extension/documents.html) before continuing reading.
+
+The front-end's models are more complicated because JupyterLab wraps the shared models (that is how we name Jupyter YDoc in the JupyterLab source code) inside the old document's models from JupyterLab. In addition, JupyterLab's document models expose the shared models as a single property, and registering new documents involves more knowledge of the document system. For this reason, we recommend following JupyterLab's documentation, [the section about documents](https://jupyterlab.readthedocs.io/en/stable/extension/documents.html) to register new documents on the front-end side.
+
+On the other side, to export a back-end model, we have to use the entry points provided by Python. We can export our new models by adding them to the configuration file of our Python project using the entry point `jupyter_ydoc`. For example, using a `pyproject.toml` configuration file, we will export our custom model for a `my_document` type as follows:
+
+```toml
+[project.entry-points.jupyter_ydoc]
+my_document = "my_module.my_file:YCustomDocument"
+```
+
+You can find an example of a custom document in the [JupyterCAD extension](https://github.com/QuantStack/jupytercad). With an implementation of a new document model [here](https://github.com/QuantStack/jupytercad/blob/main/jupytercad/jcad_ydoc.py) and registering it [here](https://github.com/QuantStack/jupytercad/blob/main/setup.cfg).

docs/source/overview.md

@@ -1,3 +1,28 @@
 # Overview
 
-Coming soon!
+The `jupyter_ydoc` repository includes various models that JupyterLab uses for collaborative editing. These models use a specific implementation of a CRDT, the Y-CRDTs. To be more precise, the JavaScript package uses [yjs](https://github.com/yjs/yjs), while the Python package uses [y_py](https://github.com/y-crdt/ypy).
+
+Jupyter YDoc was designed to centralize the data structures used for composing a document in a single class, hide the complicated edge cases of CRDTs, and prevent users from inserting invalid data or adding new attributes to the document that are not part of the schema.
+
+This repository holds a JavaScript package and its Python counterpart. In the JupyterLab context, the JavaScript package, or from now on, `@jupyter/ydoc`, contains the front-end models used to keep the documents in the client's memory. In contrast, the Python package contains the models used in the back-end to serve documents to each client.
+
+
+## `@jupyter/ydoc`
+Built on top of [yjs](https://github.com/yjs/yjs), `@jupyter/ydoc` is a JavaScript package that includes the models used in the JupyterLab front-end for real-time collaboration. This package contains two main classes, `YFile` used for plain text documents and `YNotebook` used for the Notebook format. In the JupyterLab context, we call the models exported by this package, shared models. In addition, this package contains the `IShared` interfaces used to abstract out the implementation of the shared models in JupyterLab to make it easier to replace the CRDT implementation (Yjs) for something else if needed.
+
+**Source Code:** [GitHub](https://github.com/jupyter-server/jupyter_ydoc/tree/main/javascript)
+
+**Package:** [NPM](https://www.npmjs.com/package/@jupyter/ydoc)
+
+**API documentation:**: [JavaScript API](javascript_api.rst)
+
+
+
+## `jupyter-ydoc`
+Built on top of [y_py](https://github.com/y-crdt/ypy), `jupyter-ydoc` is a Python package that includes the models used in the JupyterLab back-end for representing collaborative documents.
+
+**Source Code:** [GitHub](https://github.com/jupyter-server/jupyter_ydoc/tree/main/jupyter_ydoc)
+
+**Package:** [PyPI](https://pypi.org/project/jupyter-ydoc)
+
+**API documentation:**: [Python API](python_api.rst)

docs/source/schema.md

@@ -1,10 +1,129 @@
 # Schemas
 
+Yjs is untyped. We must know what each attribute contains at build-time and cast its values when accessing them. It is essential to ensure both models use the same schema, to prevent errors at run-time because of a wrong cast. For this purpose, in the following sections, we can find the description of the schema used by each model in case we want to extend them to create a custom model.
+
 ## YFile
 
-Coming soon!
+```typescript
+{
+	/**
+	 * Contains the state of the document.
+	 * At the moment the only mandatory attributes are path and dirty.
+	*/
+	"state": YMap<string, any>,
+	/**
+	 * Contains the content of the document.
+	*/
+	"source": YText
+
+}
+```
 
+### state:
+```typescript
+{
+	/**
+	 * Whether the document is dirty.
+	*/
+	"dirty": bool,
+	/**
+	 * Document's path.
+	*/
+	"path": str
+}
+```
 
 ## YNotebook
 
-Coming soon!
+```typescript
+{
+	/**
+	 * Contains the state of the document.
+	 * At the moment the only mandatory attributes are path and dirty.
+	*/
+	"state": YMap<string, any>,
+	/**
+	 * Contains document's metadata.
+	 *
+	 * Note: Do not confuse it with the notebook's metadata attribute,
+	 * "meta" has `nbformat`, `nbformat_minor`, and `metadata`
+	*/
+	"meta": YMap<string, any>,
+	/**
+	 * The list of YMap that stores the data of each cell.
+	*/
+	"cells": YArray<YMap<string, any>>
+}
+```
+
+### state:
+```typescript
+{
+	/**
+	 * Whether the document is dirty.
+	*/
+	"dirty": bool,
+	/**
+	 * Document's path.
+	*/
+	"path": str
+}
+```
+
+### meta:
+```typescript
+{
+	/**
+	 * The version of the notebook format supported by the schema.
+	*/
+	"nbformat": number,
+	/**
+	 * The minor version of the notebook format.
+	*/
+	"nbformat_minor": number,
+	/**
+	 * Notebook's metadata.
+	*/
+	"metadata": YMap<string, any>
+}
+```
+
+### cells
+```typescript
+[
+	/**
+	 * The following JSON object is actually a YMap that contains
+	 * the described attributes.
+	*/
+	{
+		/**
+		 * Cell's id.
+		*/
+		"id": str,
+		/**
+		 * Cell type.
+		*/
+		"cell_type": str,
+		/**
+		 * The content of the cell (the code).
+		*/
+		"source": YText,
+		/**
+		 * Cell's metadata.
+		*/
+		"metadata": YMap<string, any>,
+		/**
+		 * The execution count.
+		*/
+		"execution_count": Int | None,
+		/**
+		 * Cell's outputs.
+		*/
+		"outputs": [] | None,
+		/**
+		 * Cell's attachments.
+		*/
+		"attachments": {} | None
+	}
+]
+```