Merge pull request #96 from blink1073/cleanup-docs

Clean up notebook docs and add links

tutorial/documents.md

@@ -1,7 +1,7 @@
 # Documents
-The Document Registry is the default mechanism for interacting with
-files in JupyterLab.  The Document Manager uses it to create models and 
-widgets for documents.  The File Browser uses the Document Manager when 
+The [Document Registry](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html) is the default mechanism for interacting with
+files in JupyterLab.  The [Document Manager](http://jupyter.org/jupyterlab/classes/_docmanager_manager_.documentmanager.html) uses it to create models and 
+widgets for documents.  The [File Browser](http://jupyter.org/jupyterlab/classes/_filebrowser_browser_.filebrowserwidget.html) uses the Document Manager when 
 creating and opening files.
 
 The Document Manager handles models, contexts, and widgets for documents 
@@ -10,34 +10,34 @@ and manages their life cycle.
 Extensions in the JupyterLab application can register widget factories, 
 model factories, widget extensions, file types, and file creators.
 
-## Widget Factories 
+## [Widget Factories](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registerwidgetfactory)
 Create a widget for a given file. An example is the notebook widget 
 factory that creates NotebookPanel widgets.
 
-## Model Factories 
+## [Model Factories](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registermodelfactory)
 Create a model for a given file.  Models are generally differentiated by 
 the contents options used to fetch the model (e.g. text, base64, notebook).
 
-## Widget Extensions
+## [Widget Extensions](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registerextension)
 Add additional functionality to a widget type. An extension instance is 
 created  for each widget instance.  An example is the ipywidgets extension 
 that is created for NotebookPanel widgets.  Another example would be to add a 
 button to the toolbar of each NotebookPanel widget.
 
-## File Types 
+## [File Types](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registerfiletype)
 Intended to be used in a "Create New" dialog, providing a list of known 
 file types.
 
-## File Creators 
+## [File Creators](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registercreator)
 Intended for create quick launch file creators. The default use will be for 
 the "create new" dropdown in the file browser, giving list of items that can 
 be created with default options  (e.g. "Python 3 Notebook").
 
-## Document Models
+## [Document Models](http://jupyter.org/jupyterlab/interfaces/_docregistry_interfaces_.idocumentmodel.html)
 Created by the model factories and passed to widget factories and widget 
 extensions.
 
-## Document Contexts
+## [Document Contexts](http://jupyter.org/jupyterlab/interfaces/_docregistry_interfaces_.idocumentcontext.html)
 Created by the Document Manager and passed to widget factories and
 widget extensions.  They are used to provide an abstracted interface
 to the session and contents API from jupyter-js-services for the 
@@ -46,7 +46,7 @@ The reason for a separate context and model is so that it is easy to create
 model factories and the heavy lifting of the context is left to the Document
 Manager.
 
-## Document Wrappers
+## [Document Wrappers](http://jupyter.org/jupyterlab/classes/_docmanager_manager_.documentwrapper.html)
 The top level widget created by the Document Manager that wraps the widget 
 returned by the widget factory.  They are used because they can be
 created synchronously, while the widgets created using the widget

tutorial/extensions.md

@@ -18,10 +18,10 @@ application.
 - Services are activated when they are needed by other services or extensions.
 
 The default services providers in the JupyterLab application include:
-- Services - An application-specific interface to `jupyter-js-services`.
-- RenderMime - The registry for adding kernel `display_data` renderers.
-- Document Registry - Used to add functionality around widgets backed by files.
-- Clipboard - The application-wide clipboard for arbitrary MIME data.
+- [Services](http://jupyter.org/jupyterlab/modules/_services_plugin_.html#servicesprovider) - An application-specific interface to `jupyter-js-services`.
+- [RenderMime](http://jupyter.org/jupyterlab/modules/_rendermime_plugin_.html#rendermimeprovider) - The registry for adding kernel `display_data` renderers.
+- [Document Registry](http://jupyter.org/jupyterlab/modules/_docregistry_plugin_.html#docregistryprovider) - Used to add functionality around widgets backed by files.
+- [Clipboard](http://jupyter.org/jupyterlab/modules/_clipboard_plugin_.html#clipboardprovider) - The application-wide clipboard for arbitrary MIME data.
 
 ## [Extensions](https://github.com/phosphorjs/phosphide/blob/master/src/core/extensionregistry.ts#L19) 
 Extensions use the Application object and optionally other services to provide 
@@ -30,15 +30,14 @@ functionality to the application.
 - Extensions can also be activated explicitly at runtime through the Application [instance](https://github.com/phosphorjs/phosphide/blob/master/src/core/application.ts#L71).
 
 The default extensions in the application include:
-- Command palette - Adds the command palette widget to the sidebar.
-- Widget manager - Manages comm channels for ipywidgets.
-- Terminal - Adds the ability to create command prompt terminals.
-- Shortcuts - Provides the default set of shortcuts for the application.
-- Images - Adds a widget factory for displaying image files.
-- Help - Adds a side bar widget for displaying external documentation.
-- File Browser - Creates the file browser and the document manager and the file browser to the side bar.
-- Editor - Add a widget factory for displaying editable source files.
-- Console - Adds the ability to launch Jupyter Console instances for
+- [Widget manager](http://jupyter.org/jupyterlab/modules/_widgets_plugin_.html#widgetmanagerextension) - Manages comm channels for ipywidgets.
+- [Terminal](http://jupyter.org/jupyterlab/modules/_terminal_plugin_.html) - Adds the ability to create command prompt terminals.
+- [Shortcuts](http://jupyter.org/jupyterlab/modules/_shortcuts_plugin_.html) - Provides the default set of shortcuts for the application.
+- [Images](http://jupyter.org/jupyterlab/modules/_imagewidget_plugin_.html) - Adds a widget factory for displaying image files.
+- [Help](http://jupyter.org/jupyterlab/modules/_help_plugin_.html) - Adds a side bar widget for displaying external documentation.
+- [File Browser](http://jupyter.org/jupyterlab/modules/_filebrowser_plugin_.html) - Creates the file browser and the document manager and the file browser to the side bar.
+- [Editor](http://jupyter.org/jupyterlab/modules/_editorwidget_plugin_.html) - Add a widget factory for displaying editable source files.
+- [Console](http://jupyter.org/jupyterlab/modules/_console_plugin_.html) - Adds the ability to launch Jupyter Console instances for
 interactive kernel console sessions.
 
 

tutorial/notebook.md

@@ -1,24 +1,24 @@
 # Notebook
 
-The NotebookWidgetFactory constructs a new NotebookPanel from a model and populates the toolbar with default widgets.
+The [NotebookWidgetFactory](http://jupyter.org/jupyterlab/classes/_notebook_notebook_widgetfactory_.notebookwidgetfactory.html) constructs a new [NotebookPanel](http://jupyter.org/jupyterlab/classes/_notebook_notebook_panel_.notebookpanel.html) from a model and populates the toolbar with default widgets.
 
 ## Model
 
-The NotebookModel contains an observable list of cells (which implements undo functionality). A cell can be a code cell, a markdown cell, or a raw cell. A code cell contains a list of output models. The list of cells and the list of outputs can be observed for changes. 
+The [NotebookModel](http://jupyter.org/jupyterlab/classes/_notebook_notebook_model_.notebookmodel.html) contains an observable list of cells (which implements undo functionality). A [cell model](http://jupyter.org/jupyterlab/modules/_notebook_cells_model_.html) can be a code cell, a markdown cell, or a raw cell. A code cell contains a list of output models. The list of cells and the list of outputs can be observed for changes. 
 
-The notebook model cell list supports undo/redo on cell list operations (such as moving cells or adding/deleting cells). Compound operations are also supported. Right now, undo/redo is not supported on other notebook attributes, such as notebook metadata. Undo/redo for individual cell input content is supported by the codemirror editor undo (which does not cover cell metadata changes).
+The notebook model cell list supports undo/redo on cell list operations (such as moving cells or adding/deleting cells). Compound operations are also supported. Right now, undo/redo is not supported on other notebook attributes, such as notebook metadata. Undo/redo for individual cell input content is supported by the CodeMirror editor undo (which does not cover cell metadata changes).
 
-The notebook model and notebook cells support getting and setting metadata through cursors. You can request a cursor to write to a specific metadata key from a notebook model or a cell model.
+The notebook model and notebook cells support getting and setting metadata through cursors. One can request a cursor to write to a specific metadata key from a notebook model or a cell model.
 
 ## Notebook widget
 
-The widget embedded into the DockPanel is the NotebookPanel. The NotebookPanel contains a NotebookToolbar and a Notebook widget and handles the completion logic. The NotebookToolbar maintains a list of widgets to add to the toolbar. The Notebook widget contains the rendering of the notebook and handles most of the interaction logic with the notebook itself (such as keeping track of selected and active cells and the current edit/command mode).
+The widget embedded into the DockPanel is the NotebookPanel. The NotebookPanel contains a [NotebookToolbar](http://jupyter.org/jupyterlab/classes/_notebook_notebook_toolbar_.notebooktoolbar.html) and a [Notebook widget](http://jupyter.org/jupyterlab/classes/_notebook_notebook_widget_.notebook.html) and adds completion logic. The NotebookToolbar maintains a list of widgets to add to the toolbar. The Notebook widget contains the rendering of the notebook and handles most of the interaction logic with the notebook itself (such as keeping track of selected and active cells and the current edit/command mode).
 
-The notebook model cell list provides ways to do fine-grained changes to the cell list. Higher-level actions are contained in the NotebookActions namespace, which has functions to (given a notebook widget) run a cell and select the next cell, merge or split cells at the cursor, delete selected cells, etc.
+The notebook model cell list provides ways to do fine-grained changes to the cell list. Higher-level actions are contained in the [NotebookActions](http://jupyter.org/jupyterlab/modules/_notebook_notebook_actions_.notebookactions.html) namespace, which has functions to (given a notebook widget) run a cell and select the next cell, merge or split cells at the cursor, delete selected cells, etc.
 
-A Notebook widget contains a list of cell widgets, corresponding to the cell models in its cell list. Each cell widget contains an InputAreaWidget, which contains a CellEditorWidget, which contains a Codemirror instance. A CodeCellWidget also contains an OutputAreaWidget. An OutputAreaWidget is responsible for rendering the outputs in the ObservableOutputs list in the corresponding code cell model. An OutputAreaWidget uses a notebook-specific RenderMime object to render `display_data` output messages (see the OutputAreaWidget.createOutput function).
+A Notebook widget contains a list of [cell widgets](http://jupyter.org/jupyterlab/modules/_notebook_cells_widget_.html), corresponding to the cell models in its cell list. Each cell widget contains an [InputAreaWidget](http://jupyter.org/jupyterlab/classes/_notebook_cells_widget_.inputareawidget.html), which contains a [CellEditorWidget](http://jupyter.org/jupyterlab/classes/_notebook_cells_editor_.celleditorwidget.html), which contains a CodeMirror instance. A [CodeCellWidget](http://jupyter.org/jupyterlab/classes/_notebook_cells_widget_.codecellwidget.html) also contains an [OutputAreaWidget](http://jupyter.org/jupyterlab/classes/_notebook_output_area_widget_.outputareawidget.html). An OutputAreaWidget is responsible for rendering the outputs in the [ObservableOutputs](http://jupyter.org/jupyterlab/classes/_notebook_output_area_model_.observableoutputs.html) list in the corresponding code cell model. An OutputAreaWidget uses a notebook-specific [RenderMime](http://jupyter.org/jupyterlab/classes/_rendermime_index_.rendermime.html) object to render `display_data` output messages.
 
-A Rendermime plugin provides a pluggable system for rendering output messages. Default renderers are provided for markdown, html, images, text, etc. Extensions can register renderers to be used across the entire application by registering a handler and mimetype in the rendermime registry. When a notebook is created, it copies the global Rendermime singleton so that notebook-specific renderers can be added. The widget manager is an example of an extension that adds a notebook-specific renderer, since rendering a widget depends on notebook-specific widget state.
+A Rendermime plugin provides a pluggable system for rendering output messages. Default renderers are provided for markdown, html, images, text, etc. Extensions can register renderers to be used across the entire application by registering a handler and mimetype in the rendermime registry. When a notebook is created, it copies the global Rendermime singleton so that notebook-specific renderers can be added. The ipywidgets widget manager is an example of an extension that adds a notebook-specific renderer, since rendering a widget depends on notebook-specific widget state.
 
 ## Notebook extensions
 
@@ -104,6 +104,7 @@ Then add this extension to the JupyterLab extension list and relaunch JupyterLab
 
 This discussion will be a bit confusing since we've been using "widget" to refer to phosphor widgets. In the discussion below, ipython widgets will be referred to as "ipywidgets". There is no intrinsic relation between phosphor widgets and ipython widgets.
 
-The ipywidgets plugin registers a factory for a notebook extension. The `createNew()` function is called with a NotebookPanel and DocumentContext. The plugin then creates a ipywidget manager (which uses the context to interact the kernel and kernel's comm manager). The plugin then registers an ipywidget renderer with the notebook instance's rendermime (which is specific to that particular notebook).
+The ipywidgets plugin registers a factory for a notebook widget extension 
+using the [Document Registry](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registermodelfactory). The `createNew()` function is called with a NotebookPanel and [DocumentContext](http://jupyter.org/jupyterlab/interfaces/_docregistry_interfaces_.idocumentcontext.html). The plugin then creates a ipywidget manager (which uses the context to interact the kernel and kernel's comm manager). The plugin then registers an ipywidget renderer with the notebook instance's rendermime (which is specific to that particular notebook).
 
-When an ipywidget model is created in the kernel, a comm message is sent to the browser and handled by the ipywidget manager to create a browser-side ipywidget model. When the model is displayed in the kernel, a `display_data` output is sent to the browser with the ipywidget model id. The renderer registered in that notebook's rendermime is asked to render the output. The renderer asks the ipywidget manager instance to render the corresponding model, which returns a javascript promise. The renderer creates a container *phosphor* widget which it hands back synchronously to the OutputAreaWidget, and then fills the container with the rendered ipywidget when the promise resolves.
+When an ipywidget model is created in the kernel, a comm message is sent to the browser and handled by the ipywidget manager to create a browser-side ipywidget model. When the model is displayed in the kernel, a `display_data` output is sent to the browser with the ipywidget model id. The renderer registered in that notebook's rendermime is asked to render the output. The renderer asks the ipywidget manager instance to render the corresponding model, which returns a javascript promise. The renderer creates a container *phosphor* widget which it hands back synchronously to the OutputAreaWidget, and then fills the container with the rendered ipywidget when the promise resolves.