May 25, 2018 · Apr 23, 2018 · Apr 24, 2018 · Apr 25, 2018 · Apr 26, 2018 · Apr 27, 2018
diff --git a/docs/source/developer/documents.rst b/docs/source/developer/documents.rst
 For this section, the term 'document' refers to any visual thing that
 is backed by a file stored on disk (e.g. uses Contents API).

 Overview of document architecture
 ---------------------------------

 A 'document' in JupyterLab is represented by a model instance implementing the `IModel http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.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 http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.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. Models for the same file path do not directly communicate with each other.

 `Document widgets http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.documentregistry.ireadywidget.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 <http://jupyterlab.github.io/jupyterlab/classes/_docregistry_src_registry_.documentregistry.html>`__
 is where document types and factories are registered. Plugins can

 *Document widget extensions* in the JupyterLab application can register:

 -  widget factories
 -  model factories
 -  widget extension factories
 -  file types
 -  model factories for specific file types
 -  widget factories for specific model factories
 -  widget extension factories
 -  file creators

 `Widget Factories <http://jupyterlab.github.io/jupyterlab/classes/_docregistry_src_registry_.documentregistry.html#addwidgetfactory>`__

 The *File Browser* uses the *Document Manager* to open documents and
 manage them.


 New Documents Docs
 ------------------

 A 'document' in JupyterLab is represented by a model instance implementing the `IModel http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.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 http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.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. Models for the same file path do not directly communicate with each other.

 `Document widgets http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.documentregistry.ireadywidget.html`__ represent a view of a document model. There can be multiple document widgets associated with a single document model, and they can naturally stay in sync with each other since they are views on the same underlying data model.

 Registration
 ^^^^^^^^^^^^

 Factory functions registered with the docregistry create document models and widgets.

 Models
 ~~~~~~
 A plugin can register a model factory function associated with specific file types. A plugin can also register new file types with the docregistry.

 Widgets
 ^^^^^^^

 A plugin can register a widget factory function associated with specific model factory names.


 Creation
 ^^^^^^^^
 A document widget is created from JupyterLab (for example, by a user opening a file). The widget creation causes the associated model to be created if it is not already created.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -15,6 +15,16 @@ JupyterLab can be extended in several ways:
		For this section, the term 'document' refers to any visual thing that
		is backed by a file stored on disk (e.g. uses Contents API).
Copy link Member ian-r-roseMay 22, 2018 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I actually think "i.e" makes more sense here 😄 Copy link ContributorAuthor jasongroutMay 23, 2018 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. facepalm - Yep!

		Overview of document architecture
		---------------------------------

		A 'document' in JupyterLab is represented by a model instance implementing the `IModel http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.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 http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.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. Models for the same file path do not directly communicate with each other.
Copy link Member ian-r-roseMay 24, 2018 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I thought this sentence was kind of misleading. File views sharing the same modeldo communicate with each other. Perhaps "Different models for the same file path"? Copy link ContributorAuthor jasongroutMay 24, 2018 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Sure.

		`Document widgets http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.documentregistry.ireadywidget.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 <http://jupyterlab.github.io/jupyterlab/classes/_docregistry_src_registry_.documentregistry.html>`__
		is where document types and factories are registered. Plugins can
Expand All		@@ -32,10 +42,10 @@ Document Registry

		Document widget extensions in the JupyterLab application can register:

		- widget factories
		- model factories
		- widget extension factories
		- file types
		- model factories for specific file types
		- widget factories for specific model factories
		- widget extension factories
		- file creators

		`Widget Factories <http://jupyterlab.github.io/jupyterlab/classes/_docregistry_src_registry_.documentregistry.html#addwidgetfactory>`__
Expand DownExpand Up		@@ -118,33 +128,3 @@ The Document Manager handles:

		The File Browser uses the Document Manager to open documents and
		manage them.


		New Documents Docs
		------------------

		A 'document' in JupyterLab is represented by a model instance implementing the `IModel http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.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 http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.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. Models for the same file path do not directly communicate with each other.

		`Document widgets http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.documentregistry.ireadywidget.html`__ represent a view of a document model. There can be multiple document widgets associated with a single document model, and they can naturally stay in sync with each other since they are views on the same underlying data model.

		Registration
		^^^^^^^^^^^^

		Factory functions registered with the docregistry create document models and widgets.

		Models
		~~~~~~
		A plugin can register a model factory function associated with specific file types. A plugin can also register new file types with the docregistry.

		Widgets
		^^^^^^^

		A plugin can register a widget factory function associated with specific model factory names.


		Creation
		^^^^^^^^
		A document widget is created from JupyterLab (for example, by a user opening a file). The widget creation causes the associated model to be created if it is not already created.