User documentation (#3534)

* Moving files into separate source directory.

* Working build with new layout.

* Moving and updating conf.py

* More work on docs.

* More work on the docs.

* More work on docs.

* Final docs work.

* Add note about image naming.

* Update relative links

* Rename testapp -> processtestapp to avoid pytest warning

docs/Makefile

@@ -1,225 +1,20 @@
-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = _build
+SPHINXBUILD   = python -msphinx
+SPHINXPROJ    = JupyterLab
+SOURCEDIR     = source
+BUILDDIR      = build
 
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  applehelp  to make an Apple Help Book"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  epub3      to make an epub3"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  xml        to make Docutils-native XML files"
-	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-	@echo "  coverage   to run coverage check of the documentation (if enabled)"
-	@echo "  dummy      to check syntax errors of document sources"
-
-.PHONY: clean
-clean:
-	rm -rf $(BUILDDIR)/*
-
-.PHONY: html
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-.PHONY: dirhtml
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-.PHONY: singlehtml
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-.PHONY: pickle
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-.PHONY: json
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-.PHONY: htmlhelp
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-.PHONY: qthelp
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/JupyterLabTutorial.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/JupyterLabTutorial.qhc"
-
-.PHONY: applehelp
-applehelp:
-	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
-	@echo
-	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
-	@echo "N.B. You won't be able to view it unless you put it in" \
-	      "~/Library/Documentation/Help or install it in your application" \
-	      "bundle."
-
-.PHONY: devhelp
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/JupyterLabTutorial"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/JupyterLabTutorial"
-	@echo "# devhelp"
-
-.PHONY: epub
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-.PHONY: epub3
-epub3:
-	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
-	@echo
-	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
-
-.PHONY: latex
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-.PHONY: latexpdf
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-.PHONY: latexpdfja
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-.PHONY: text
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-.PHONY: man
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-.PHONY: texinfo
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-.PHONY: info
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-.PHONY: gettext
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-.PHONY: changes
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-.PHONY: linkcheck
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-.PHONY: doctest
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
-
-.PHONY: coverage
-coverage:
-	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
-	@echo "Testing of coverage in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/coverage/python.txt."
-
-.PHONY: xml
-xml:
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
-	@echo
-	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: pseudoxml
-pseudoxml:
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
-	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+.PHONY: help Makefile
 
-.PHONY: dummy
-dummy:
-	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
-	@echo
-	@echo "Build finished. Dummy builder generates no files."
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -1,360 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
-# JupyterLab Tutorial documentation build configuration file, created by
-# sphinx-quickstart on Tue Jun 21 16:30:09 2016.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-import sys
-import os
-import shlex
-
-# For conversion from markdown to html
-import recommonmark.parser
-from recommonmark.transform import AutoStructify
-
-# Set paths
-#sys.path.insert(0, os.path.abspath('.'))
-
-# -- General configuration ------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-needs_sphinx = '1.4'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    'sphinx.ext.mathjax',
-    'jupyter_alabaster_theme'
-]
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The encoding of source files.
-#
-# source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = 'JupyterLab Tutorial'
-copyright = '2017, Project Jupyter'
-author = 'Project Jupyter'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '0.1'
-# The full version, including alpha/beta/rc tags.
-release = '0.1'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#
-# today = ''
-#
-# Else, today_fmt is used as the format for a strftime call.
-#
-# today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-#
-# default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#
-# add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#
-# add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#
-# show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-# modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-# keep_warnings = False
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
-# -- Source -------------------------------------------------------------
-
-source_parsers = {
-    '.md': 'recommonmark.parser.CommonMarkParser',
-}
-
-source_suffix = ['.rst', '.md']
-
-# -- Options for HTML output ----------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = 'jupyter_alabaster_theme'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-# html_theme_options = {}
-
-# Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
-
-# The name for this set of Sphinx documents.
-# "<project> v<release> documentation" by default.
-#
-# html_title = 'JupyterLab Tutorial v0.1'
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#
-# html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#
-# html_logo = None
-
-# The name of an image file (relative to this directory) to use as a favicon of
-# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#
-# html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
-
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-#
-# html_extra_path = []
-
-# If not None, a 'Last updated on:' timestamp is inserted at every page
-# bottom, using the given strftime format.
-# The empty string is equivalent to '%b %d, %Y'.
-#
-# html_last_updated_fmt = None
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#
-# html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#
-# html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#
-# html_additional_pages = {}
-
-# If false, no module index is generated.
-#
-# html_domain_indices = True
-
-# If false, no index is generated.
-#
-# html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#
-# html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#
-# html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#
-# html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#
-# html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#
-# html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-# html_file_suffix = None
-
-# Language to be used for generating the HTML full-text search index.
-# Sphinx supports the following languages:
-#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
-#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh'
-#
-# html_search_language = 'en'
-
-# A dictionary with options for the search language support, empty by default.
-# 'ja' uses this config value.
-# 'zh' user can custom change `jieba` dictionary path.
-#
-# html_search_options = {'type': 'default'}
-
-# The name of a javascript file (relative to the configuration directory) that
-# implements a search results scorer. If empty, the default will be used.
-#
-# html_search_scorer = 'scorer.js'
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'JupyterLabTutorialdoc'
-
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-     # The paper size ('letterpaper' or 'a4paper').
-     #
-     # 'papersize': 'letterpaper',
-
-     # The font size ('10pt', '11pt' or '12pt').
-     #
-     # 'pointsize': '10pt',
-
-     # Additional stuff for the LaTeX preamble.
-     #
-     # 'preamble': '',
-
-     # Latex figure (float) alignment
-     #
-     # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, 'JupyterLabTutorial.tex', 'JupyterLab Tutorial Documentation',
-     'Project Jupyter', 'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#
-# latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#
-# latex_use_parts = False
-
-# If true, show page references after internal links.
-#
-# latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#
-# latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#
-# latex_appendices = []
-
-# If false, no module index is generated.
-#
-# latex_domain_indices = True
-
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'jupyterlabtutorial', 'JupyterLab Tutorial Documentation',
-     [author], 1)
-]
-
-# If true, show URL addresses after external links.
-#
-# man_show_urls = False
-
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (master_doc, 'JupyterLabTutorial', 'JupyterLab Tutorial Documentation',
-     author, 'JupyterLabTutorial', 'One line description of project.',
-     'Miscellaneous'),
-]
-
-
-# Documents to append as an appendix to all manuals.
-#
-# texinfo_appendices = []
-
-# If false, no module index is generated.
-#
-# texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#
-# texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#
-# texinfo_no_detailmenu = False
-
-# autodoc configuration with AutoStructify
-#
-# See http://recommonmark.readthedocs.io/en/latest/auto_structify.html
-# See the setup function in current conf.py file in the recommonmark repo
-# https://github.com/rtfd/recommonmark/blob/master/docs/conf.py#L296
-github_doc_root = 'https://github.com/jupyterlab/jupyterlab/tree/master/docs/'
-def setup(app):
-    app.add_config_value('recommonmark_config', {
-        'url_resolver': lambda url: github_doc_root + url,
-        'auto_toc_tree_section': 'Contents',
-        'enable_eval_rst': True,
-        'enable_auto_doc_ref': False,
-    }, True)
-    app.add_transform(AutoStructify)

docs/environment.yml

@@ -1,4 +1,4 @@
-name: lab_tutorial
+name: jupyterlab_documentation
 channels:
   - conda-forge
 dependencies:
@@ -6,5 +6,4 @@ dependencies:
 - sphinx>=1.6
 - sphinx_rtd_theme
 - pip:
-  - jupyter_alabaster_theme
   - recommonmark==0.4.0

docs/extensions_user.md

@@ -1,147 +0,0 @@
-# Extensions User Guide
-
-JupyterLab extensions add functionality to the JupyterLab application.
-They can provide new file viewer types, launcher activities, and new Notebook
-output renderers for example.
-
-### Installing Node.js
-
-Installing JupyterLab extensions requires Node.js version 4+.
-
-If you use ``conda``, you can get them with:
-
-```bash
-conda -c conda-forge install nodejs
-```
-
-If you use [Homebrew](http://brew.sh/) on Mac OS X:
-
-```bash
-brew install node
-```
-
-### Installing Extensions
-
-The base JupyterLab application comes with core set of extensions, which
-provide the Notebook, Terminal, Text Editor, etc.  New extensions can be
-installed into the application using the command:
-
-```
-jupyter labextension install <foo>
-```
-
-Where `<foo>` is a valid JupyterLab extension specifier.  This specifier
-is defined by the extension author in their installation instructions.
-
-The currently installed extensions can be listed by running the command:
-
-```
-jupyter labextension list
-```
-
-An installed extension can be uninstalled by running the command:
-
-```
-jupyter labextension uninstall <bar>
-```
-
-Where `<bar>` is the name of the extension, as printed in the extension
-list.  Core extensions can also be uninstalled this way (and can later be
-re-installed).
-
-Extensions can be disabled by running the command:
-
-```
-jupyter labextension disable <foo>
-```
-
-Where `<foo>` is the name of the extension.  This will prevent the
-extension from loading on the front end, but does not require a rebuild.
-The extension can be re-enabled using the command:
-
-```
-jupyter labextension enable <foo>
-```
-
-Core plugins can also be disabled (and then re-enabled).
-
-
-## Advanced usage
-
-The JupyterLab application directory (where the application assets are
-built and the settings reside) can be overridden using `--app-dir` in
-any of the JupyterLab commands, or by setting the `JUPYTERLAB_DIR` environment
-variable.  If not specified, it will default to
-`<sys-prefix/share/jupyter/lab`, where `sys-prefix` is the
-site-specific directory prefix of the current Python environment.  You can
-query the current application path using `jupyter lab path`.
-
-To create the app directory without installing any extensions, run `jupyter lab build`.
-The `install` and `link` commands already run the build, so it typically
-does not need to be called directly.
-
-Building consists of:
-
-- Populating the `staging/` directory using template files
-- Handling any linked packages (see `jupyter labextension link`)
-- Ensuring all install assets are available
-- Building the assets
-- Copying the assets to the `static` directory
-
-The `settings` directory contains `page_config.json` and `build_config.json`
-files.
-
-### `page_config.json`
-
-The `page_config.json` data is used to provide config data to the application
-environment.
-
-Two important fields in the `page_config.json` file allow control of which plugins load:
-
-1. `disabledExtensions` for extensions that should not load at all.
-2. `deferredExtensions` for extensions that do not load until they are required
-by something, irrespective of whether they set `autostart` to `true`.
-
-The values for each are an array of strings. The following sequence of checks are performed against the patterns in `disabledExtensions` and `deferredExtensions`.
-
-* If an identical string match occurs between a config value and a package name (*e.g.*, `"@jupyterlab/apputils-extension"`), then the entire package is disabled (or deferred).
-* If the string value is compiled as a regular expression and tests positive against a package name (*e.g.*, `"disabledExtensions": ["@jupyterlab/apputils*$"]`), then the entire package is disabled (or deferred).
-* If an identical string match occurs between a config value and an individual plugin ID within a larger package (*e.g.*, `"disabledExtensions": ["@jupyterlab/apputils-extension:settings"]`), then that specific plugin is disabled (or deferred).
-* If the string value is compiled as a regular expression and tests positive against an individual plugin ID within a larger package (*e.g.*, `"disabledExtensions": ["^@jupyterlab/apputils-extension:set.*$"]`), then that specific plugin is disabled (or deferred).
-
-### `build_config.json`
-
-The `build_config.json` file is used to track the folders that have been
-added using `jupyter labextension link <folder>`, as well as core extensions
-that have been explicitly uninstalled.  e.g.
-
-```bash
-$ cat settings/build_config.json
-{
-    "uninstalled_core_extensions": [
-        "@jupyterlab/markdownwidget-extension"
-    ],
-    "linked_packages": {
-        "@jupyterlab/python-tests": "/path/to/my/extension"
-    }
-}
-```
-
-The other folders in the app directory are: `extensions`, `static`, and
-`staging`.  The `extensions` folder has the packed tarballs for each of the
-installed extensions for the app.  If the application directory is not the same
-as the `sys-prefix` directory, the extensions installed in the `sys-prefix`
-directory will be used in the app directory.  If an extension is installed in
-the app directory that exists in the `sys-prefix` directory, it will shadow
-the `sys-prefix` version.  Uninstalling an extension will first uninstall the
-shadowed extension, and then attempt to uninstall the `sys-prefix` version
-if called again.  If the `sys-prefix` version cannot be uninstalled, its
-plugins can still be ignored using `ignoredPackages` metadata in `settings`.
-
-The `static` folder contains the assets that will be loaded by the JuptyerLab
-application.  The `staging` folder is used to create the build and then
-populate the `static` folder.
-
-Running `jupyter lab` will attempt to run the `static` assets in the
-application folder if they exist.  You can run `jupyter lab --core-mode`
-to load the core JupyterLab application instead.

docs/index.rst

@@ -1,33 +0,0 @@
-.. JupyterLab Tutorial documentation master file, created by
-   sphinx-quickstart on Tue Jun 21 16:30:09 2016.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-JupyterLab Tutorial
-===================
-
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-
-   repo.md
-   extensions_user.md
-   extensions_dev.md
-   documents.md
-   notebook.md
-   patterns.md
-   css.md
-   virtualdom.md
-   adding_content.md
-   examples.md
-   terminology.md
-   xkcd_extension_tutorial.md
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

docs/make.bat

@@ -1,281 +1,36 @@
-@ECHO OFF
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
-set I18NSPHINXOPTS=%SPHINXOPTS% .
-if NOT "%PAPER%" == "" (
-	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
-	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
-)
-
-if "%1" == "" goto help
-
-if "%1" == "help" (
-	:help
-	echo.Please use `make ^<target^>` where ^<target^> is one of
-	echo.  html       to make standalone HTML files
-	echo.  dirhtml    to make HTML files named index.html in directories
-	echo.  singlehtml to make a single large HTML file
-	echo.  pickle     to make pickle files
-	echo.  json       to make JSON files
-	echo.  htmlhelp   to make HTML files and a HTML help project
-	echo.  qthelp     to make HTML files and a qthelp project
-	echo.  devhelp    to make HTML files and a Devhelp project
-	echo.  epub       to make an epub
-	echo.  epub3      to make an epub3
-	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
-	echo.  text       to make text files
-	echo.  man        to make manual pages
-	echo.  texinfo    to make Texinfo files
-	echo.  gettext    to make PO message catalogs
-	echo.  changes    to make an overview over all changed/added/deprecated items
-	echo.  xml        to make Docutils-native XML files
-	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
-	echo.  linkcheck  to check all external links for integrity
-	echo.  doctest    to run all doctests embedded in the documentation if enabled
-	echo.  coverage   to run coverage check of the documentation if enabled
-	echo.  dummy      to check syntax errors of document sources
-	goto end
-)
-
-if "%1" == "clean" (
-	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
-	del /q /s %BUILDDIR%\*
-	goto end
-)
-
-
-REM Check if sphinx-build is available and fallback to Python version if any
-%SPHINXBUILD% 1>NUL 2>NUL
-if errorlevel 9009 goto sphinx_python
-goto sphinx_ok
-
-:sphinx_python
-
-set SPHINXBUILD=python -m sphinx.__init__
-%SPHINXBUILD% 2> nul
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-:sphinx_ok
-
-
-if "%1" == "html" (
-	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
-	goto end
-)
-
-if "%1" == "dirhtml" (
-	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
-	goto end
-)
-
-if "%1" == "singlehtml" (
-	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
-	goto end
-)
-
-if "%1" == "pickle" (
-	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can process the pickle files.
-	goto end
-)
-
-if "%1" == "json" (
-	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can process the JSON files.
-	goto end
-)
-
-if "%1" == "htmlhelp" (
-	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can run HTML Help Workshop with the ^
-.hhp project file in %BUILDDIR%/htmlhelp.
-	goto end
-)
-
-if "%1" == "qthelp" (
-	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can run "qcollectiongenerator" with the ^
-.qhcp project file in %BUILDDIR%/qthelp, like this:
-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\JupyterLabTutorial.qhcp
-	echo.To view the help file:
-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\JupyterLabTutorial.ghc
-	goto end
-)
-
-if "%1" == "devhelp" (
-	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished.
-	goto end
-)
-
-if "%1" == "epub" (
-	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The epub file is in %BUILDDIR%/epub.
-	goto end
-)
-
-if "%1" == "epub3" (
-	%SPHINXBUILD% -b epub3 %ALLSPHINXOPTS% %BUILDDIR%/epub3
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The epub3 file is in %BUILDDIR%/epub3.
-	goto end
-)
-
-if "%1" == "latex" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "latexpdf" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	cd %BUILDDIR%/latex
-	make all-pdf
-	cd %~dp0
-	echo.
-	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "latexpdfja" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	cd %BUILDDIR%/latex
-	make all-pdf-ja
-	cd %~dp0
-	echo.
-	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "text" (
-	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The text files are in %BUILDDIR%/text.
-	goto end
-)
-
-if "%1" == "man" (
-	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The manual pages are in %BUILDDIR%/man.
-	goto end
-)
-
-if "%1" == "texinfo" (
-	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
-	goto end
-)
-
-if "%1" == "gettext" (
-	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
-	goto end
-)
-
-if "%1" == "changes" (
-	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.The overview file is in %BUILDDIR%/changes.
-	goto end
-)
-
-if "%1" == "linkcheck" (
-	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Link check complete; look for any errors in the above output ^
-or in %BUILDDIR%/linkcheck/output.txt.
-	goto end
-)
-
-if "%1" == "doctest" (
-	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Testing of doctests in the sources finished, look at the ^
-results in %BUILDDIR%/doctest/output.txt.
-	goto end
-)
-
-if "%1" == "coverage" (
-	%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Testing of coverage in the sources finished, look at the ^
-results in %BUILDDIR%/coverage/python.txt.
-	goto end
-)
-
-if "%1" == "xml" (
-	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The XML files are in %BUILDDIR%/xml.
-	goto end
-)
-
-if "%1" == "pseudoxml" (
-	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
-	goto end
-)
-
-if "%1" == "dummy" (
-	%SPHINXBUILD% -b dummy %ALLSPHINXOPTS% %BUILDDIR%/dummy
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. Dummy builder generates no files.
-	goto end
-)
-
-:end
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=python -msphinx
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+set SPHINXPROJ=JupyterLab
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
+	echo.then set the SPHINXBUILD environment variable to point to the full
+	echo.path of the 'sphinx-build' executable. Alternatively you may add the
+	echo.Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/source/_static/custom.css

@@ -0,0 +1,7 @@
+.wy-nav-side p.caption {
+  color: #F5F5F5;
+}
+
+div.wy-side-nav-search {
+  background: #F37626;
+}

docs/source/conf.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# JupyterLab documentation build configuration file, created by
+# sphinx-quickstart on Thu Jan  4 15:10:23 2018.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# For conversion from markdown to html
+import recommonmark.parser
+from recommonmark.transform import AutoStructify
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.intersphinx',
+    'sphinx.ext.mathjax']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+
+source_parsers = {
+    '.md': 'recommonmark.parser.CommonMarkParser',
+}
+
+source_suffix = ['.rst', '.md']
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'JupyterLab'
+copyright = '2018, Project Jupyter'
+author = 'Project Jupyter'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.0 Beta'
+# The full version, including alpha/beta/rc tags.
+release = '1.0 Beta'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+import sphinx_rtd_theme
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        'about.html',
+        'navigation.html',
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+        'donate.html',
+    ]
+}
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'JupyterLabdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'JupyterLab.tex', 'JupyterLab Documentation',
+     'Project Jupyter', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'jupyterlab', 'JupyterLab Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'JupyterLab', 'JupyterLab Documentation',
+     author, 'JupyterLab', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+
+# -- Options for Epub output ----------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+epub_author = author
+epub_publisher = author
+epub_copyright = copyright
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'https://docs.python.org/': None}
+
+
+# autodoc configuration with AutoStructify
+#
+# See http://recommonmark.readthedocs.io/en/latest/auto_structify.html
+# See the setup function in current conf.py file in the recommonmark repo
+# https://github.com/rtfd/recommonmark/blob/master/docs/conf.py#L296
+github_doc_root = 'https://github.com/jupyterlab/jupyterlab/tree/master/docs/'
+
+def setup(app):
+    app.add_config_value('recommonmark_config', {
+        'url_resolver': lambda url: github_doc_root + url,
+        'auto_toc_tree_section': 'Contents',
+        'enable_eval_rst': True,
+        'enable_auto_doc_ref': False,
+    }, True)
+    app.add_transform(AutoStructify)
+    app.add_stylesheet('custom.css')  # may also be an URL

docs/source/developer/documentation.md

@@ -0,0 +1,75 @@
+# Writing documentation
+
+This section provide information about writing documentation for JupyterLab.
+
+
+## Writing style
+
+* The documentation should be written in the second person, referring to the
+  reader as "you" and not using the first person plural "we." The author of the
+  documentation is not sitting next to the user, so using "we" can lead to
+  frustration when things don't work as expected.
+* Avoid words that trivialize using JupyterLab such as "simply" or "just." Tasks
+  that developers find simple or easy may not be for users.
+* Write in the active tense, so "drag the notebook cells..." rather than
+  "notebook cells can be dragged..."
+* The beginning of each section should begin with a short (1-2 sentence)
+  high-level description of the topic, feature or component.
+
+## Proper nouns
+
+The main parts of JupyterLab should be treated as proper nouns and capitalized:
+
+* Main Menu
+* Left Panel
+* Dock Panel
+* File Browser
+* Command Palette
+* Running List
+* Tabs List
+* Notebook
+* Code Console
+* Terminal
+
+## Keyboard shortcuts
+
+Typeset keyboard shortcuts as follows:
+
+- Monospace typeface, with no spaces between individual keys:  `Shift Enter`.
+- For modifiers, use the platform independent word describing key: `Shift`.
+- For the `Accel` key use the phrase:  `Command/Ctrl`.
+- Don’t use platform specific icons for modifier keys, as they are difficult to
+  display in a platform specific way on Sphinx/RTD.
+
+
+## Screenshots and animations
+
+Our documentation should contain screenshots and animations that illustrate and
+demonstrate the software. Here are some guidelines for preparing them:
+
+* Take screenshots and animations at the standard browser font sizes, 100%
+  browser zoom.
+* It is often helpful to have a colored background to highlight the content of
+  an animation or screenshot. If a colored background is needed, use Material
+  Design Grey 500 (`#9e9e9e`).
+* Screenshots and animations should be styled in the documentation with a
+  `max-width: 100%` property. Never stretch them wider than the original.
+* Screenshots and animations taken on high resolution screens (retina) may need
+  to be saved at half resolution to be consistent.
+* Screenshots or animations should be proceeded by a sentence describing the
+  content, such as "To open a file, double-click on its name in the File
+  Browser:".
+* Ideally each screenshot or animation should have a drop shadow, but it is unclear
+  if we should do that beforehand or in CSS (the xkcd extension tutorial has images
+  with shadowns already - let's think through this.)
+
+  To help us organize them, let's name the files like this:
+
+  ```
+  sourcefile.md
+  sourcefile_filebrowser.png
+  sourcefile_editmenu.png
+  ```
+
+  This will help us track the images next to the content they are used in.
+

docs/documents.md → docs/source/developer/documents.md

@@ -4,7 +4,7 @@ JupyterLab can be extended in two ways via:
 
 - Extensions (top level): Application extensions extend the
   functionality of JupyterLab itself, and we cover them in the
-  [Extensions](extensions_dev.md) developer tutorial.
+  [Extensions](extension_dev.md) developer tutorial.
 - **document widget extensions (lower level):** Document widget extensions extend
   the functionality of document widgets added to the application, and we cover
   them in this section.
@@ -69,7 +69,7 @@ giving list of items that can be created with default options  (e.g. "Python 3 N
 
 Created by the model factories and passed to widget factories and widget
 extension factories.  Models are the way in which we interact with the data of
-a document.  For a simple text file, we typically only use the 
+a document.  For a simple text file, we typically only use the
 `to/fromString()` methods.  A more complex document like a Notebook
 contains more points of interaction like the Notebook metadata.
 
@@ -90,7 +90,7 @@ Manager.  Contexts are not meant to be subclassed or re-implemented. Instead, th
 
 ## Document Manager
 
-The *Document Manager* handles: 
+The *Document Manager* handles:
 - document models
 - document contexts
 

docs/extensions_dev.md → docs/source/developer/extension_dev.md

@@ -1,4 +1,4 @@
-# Extensions Developer Guide
+# Extension Developer Guide
 
 JupyterLab can be extended in three ways via:
 

docs/source/developer/virtualdom.md

@@ -0,0 +1,24 @@
+# Virtual DOM and React
+
+JupyterLab is based on [PhosphorJS](http://phosphorjs.github.io/), which
+provides a flexible `Widget` class that handles the following:
+
+* Resize events that propagate down the Widget heirarchy.
+* Lifecycle events (`onBeforeDetach`, `onAfterAttach`, etc.).
+* Both CSS-based and absolutely postioned layouts.
+
+In situations where these feature are needed, we recommend using Phosphor's
+`Widget` class directly.
+
+The idea of virtual DOM rendering, which became popular in the
+[React](https://facebook.github.io/react/) community, is a very elegant and
+efficient way of rendering and updating DOM content in response to model/state
+changes.
+
+Phosphor's `Widget` class integrates well with ReactJS and we are now using
+React in JupyterLab to render leaf content when the above capabilities are not
+needed.
+
+An example of using React with Phosphor can be found in the
+[launcher](https://github.com/jupyterlab/jupyterlab/blob/master/packages/launcher/src/index.tsx)
+of JupyterLab.

docs/xkcd_extension_tutorial.md → docs/source/developer/xkcd_extension_tutorial.md

@@ -111,8 +111,8 @@ npm run build
 jupyter labextension install .
 ```
 
-After the build completes, open a second terminal.  Run these commands to 
-activate the `jupyterlab-ext` environment and to start a JupyterLab instance 
+After the build completes, open a second terminal.  Run these commands to
+activate the `jupyterlab-ext` environment and to start a JupyterLab instance
 in watch mode so that it will keep up with our changes as we make them.
 
 ```bash
@@ -273,7 +273,7 @@ Then modify the `activate` function again so that it has the following code:
 
 The first new block of code creates a `Widget` instance, assigns it a unique ID, gives it a label that will appear as its tab title, and makes the tab closable by the user. The second block of code add a new command labeled *Random xkcd comic* to JupyterLab. When the comm and executes, it attaches the widget to the main display area if it is not already present and then makes it the active tab. The last new line of code adds the command to the command palette in a section called *Tutorial*.
 
-Build your extension again using `npm run build` (unless you are using 
+Build your extension again using `npm run build` (unless you are using
 `npm run watch` already) and refresh the browser tab. Open the command palette on the left side and type *xkcd*. Your *Random xkcd comic* command should appear. Click it or select it with the keyboard and press *Enter*. You should see a new, blank panel appear with the tab title *xkcd.com*. Click the *x* on the tab to close it and activate the command again. The tab should reappear. Finally, click one of the launcher tabs so that the *xkcd.com* panel is still open but no longer active. Now run the *Random xkcd comic* command one more time. The single *xkcd.com* tab should come to the foreground.
 
 ![Empty xkcd extension panel](xkcd_tutorial_empty.png)
@@ -304,8 +304,8 @@ You've got an empty panel. It's time to add a comic to it. Go back to your code
     });
 ```
 
-The first two lines create a new HTML `<img>` element and add it to the widget DOM node. The next lines make a request using the HTML [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) 
-API that returns information about a random xkcd comic, and set the image 
+The first two lines create a new HTML `<img>` element and add it to the widget DOM node. The next lines make a request using the HTML [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)
+API that returns information about a random xkcd comic, and set the image
 source, alternate text, and title attributes based on the response.
 
 Rebuild your extension if necessary (`npm run build`), refresh your browser tab, and run the *Random xkcd comic* command again. You should now see a comic in the xkcd.com panel when it opens.
@@ -345,8 +345,8 @@ Open `style/index.css` in our extension project directory for editing. Add the f
 The first rule stacks content vertically within the widget panel and lets the panel scroll when the content overflows. The other rules center the cartoon and attribution badge horizontally and space them out vertically.
 
 Return to the `index.ts` file. Note that there is already an import of the CSS
- file in the `index.ts` file.  Modify the the `activate` function to apply the 
- CSS classes and add the attribution badge markup. The beginning of the 
+ file in the `index.ts` file.  Modify the the `activate` function to apply the
+ CSS classes and add the attribution badge markup. The beginning of the
  function should read like the following:
 
 ```typescript
@@ -378,10 +378,10 @@ Return to the `index.ts` file. Note that there is already an import of the CSS
     // as before from here down ...
 ```
 
-Build your extension if necessary (`npm run build`) and refresh your 
-JupyterLab browser tab. Invoke the *Random xkcd comic* command and confirm the 
-comic is centered with an attribution badge below it. Resize the browser 
-window or the panel so that the comic is larger than the available area. Make 
+Build your extension if necessary (`npm run build`) and refresh your
+JupyterLab browser tab. Invoke the *Random xkcd comic* command and confirm the
+comic is centered with an attribution badge below it. Resize the browser
+window or the panel so that the comic is larger than the available area. Make
 sure you can scroll the panel over the entire area of the comic.
 
 ![Styled xkcd panel with attribution](xkcd_tutorial_complete.png)
@@ -666,4 +666,4 @@ You've completed the tutorial. Nicely done! If you want to keep learning, here a
 * Make the image a link to the comic on https://xkcd.com.
 * Push your extension git repository to GitHub.
 * Give users the ability to pin comics in separate, permanent panels.
-* Learn how to write [other kinds of extensions](./extensions_dev.md).
+* Learn how to write [other kinds of extensions](./extension_dev.md).

docs/source/getting_started/installation.md

@@ -0,0 +1,36 @@
+# Installation
+
+JupyterLab can be installed using `conda` or `pip`:
+
+If you use `conda`, you can install it with:
+
+```bash
+conda install -c conda-forge jupyterlab
+```
+
+If you use `pip`, you can install it with:
+
+```bash
+pip install jupyterlab
+jupyter serverextension enable --py jupyterlab --sys-prefix
+```
+
+## Prerequisites
+
+JupyterLab requires the Jupyter Notebook version 4.3 or later. To check the
+version of the `notebook` package that you have installed:
+
+```bash
+jupyter notebook --version
+```
+
+## Supported browsers
+
+The following browsers are currently *known to work*:
+
+- Firefox Latest
+- Chrome Latest
+- Safari Latest
+
+Earlier browser versions or other browsers may also work, but come with no
+guarantees.

docs/source/getting_started/overview.md

@@ -0,0 +1,35 @@
+# Overview
+
+*JupyterLab is the next generation user interface for Project Jupyter*
+
+JupyterLab goes beyond the classic Jupyter Notebook by providing a flexible and
+extensible web application with a set of reusable components. You can arrange
+multiple notebooks, text editors, terminals, output areas, and custom components
+using tabs/panels and collapsible sidebars. These components are carefully
+designed to enable you to use them together (can send code from a file to a code
+console with a keystroke) or on their own (move cells around a notebook using
+drag-and-drop) to support novel data-driven workflows.
+
+**JupyterLab has full support for Jupyter Notebook documents.** In addition, it
+offers other models of interactive computing:
+
+* [Code Consoles]() provide transient scratchpads for running code
+  interactively, with full support for rich output.
+* [Kernel backed documents]() allow code in any text file (markdown, python, R,
+  LaTeX, etc.) to be run interactively in any Jupyter kernel.
+
+JupyterLab also offers a unified model for handling rich output and various file
+formats. This allows data in just about any format (images, CSV, JSON, markdown,
+PDF, Vega, Vega-Lite, etc.) to be opened as a file, or returned by a Kernel as
+output. See [File and output formats]() for more information.
+
+## Design principles
+
+JupyterLab should:
+
+* Use the same [server](https://jupyter-notebook.readthedocs.io/en/stable/) as
+  the classic Jupyter Notebook.
+* Use the same [notebook document
+  format](http://nbformat.readthedocs.io/en/latest/) as the classic Jupyter
+  Notebook.
+

docs/source/getting_started/starting.md

@@ -0,0 +1,25 @@
+# Starting JupyterLab
+
+Start JupyterLab using:
+
+```bash
+jupyter lab
+```
+
+JupyterLab will open automatically in your browser. You may also access
+JupyterLab by entering the notebook server's URL (`http://localhost:8888`) into
+the browser.
+
+Because JupyterLab is a server extension of the classic Jupyter Notebook server,
+you can also use JupyterLab by starting the classic Jupyter Noteboook `jupyter
+notebook` and visiting the `/lab` URL (`http://localhost:8888/lab`) rather than
+`/tree` (`http://localhost:8888/tree`).
+
+Anytime you are using JupyterLab, the classic Jupyter Notebook is still
+available at this `/tree` URL (`http://localhost:8888/tree`), which makes it
+easy to go back and forth if needed.
+
+JupyterLab has the same security model as the classic Jupyter Notebook; for more
+information see the [security
+section](https://jupyter-notebook.readthedocs.io/en/stable/security.html) of the
+classic Notebook's documentation.

docs/source/index.rst

@@ -0,0 +1,56 @@
+.. JupyterLab Tutorial documentation master file, created by
+   sphinx-quickstart on Tue Jun 21 16:30:09 2016.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+JupyterLab Documentation
+========================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Getting Started
+
+   getting_started/overview
+   getting_started/installation
+   getting_started/starting
+
+.. toctree::
+   :maxdepth: 1
+   :caption: User Guide
+
+   user/interface
+   user/files
+   user/file_editor
+   user/notebook
+   user/code_console
+   user/documents_kernels
+   user/running
+   user/commands
+   user/terminal
+   user/file_formats
+   user/extensions
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Developer Guide
+
+   developer/repo
+   developer/extension_dev
+   developer/documents
+   developer/notebook
+   developer/patterns
+   developer/css
+   developer/documentation
+   developer/virtualdom
+   developer/adding_content
+   developer/examples
+   developer/terminology
+   developer/xkcd_extension_tutorial
+
+Indices and Tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

docs/source/user/code_console.md

@@ -0,0 +1,27 @@
+
+# Code Consoles
+
+Notebooks allow you to write and run code while you create a document. At times,
+it is helpful to write and run code in an exploratory manner, while not creating
+a document; a sort of transient playground for interactive code. The JupyterLab
+Code Console addresses this usage case, with full support for the rich output of
+Jupyter.
+
+Create a code console by clicking the + button in the File Browser and selecting
+the kernel:
+
+[animation]
+
+Run code using `Shift Enter` and use the up and down arrows allow you to browse
+the history of previously run code:
+
+[animation]
+
+Tab completion (`Tab`) and tooltips (`Shift Tab`) work as in the Notebook:
+
+[animation]
+
+You can clear the previous cells of the Code Console by right-clicking on the
+Code Console and selecting the “Clear Console Cells” item:
+
+[animation]

docs/source/user/commands.md

@@ -0,0 +1,13 @@
+
+# Command Palette
+
+All user actions in JupyterLab are processed through a centralized command
+system. These commands are shared and used throughout JupyterLab (Menu Bar,
+Context Menus, etc.). The Command Palette provides a keyboard-driven way to
+search for and run any JupyterLab command:
+
+[screenshot]
+
+The Command Palette can be accessed using the keyboard shortcut Command-Shift-C:
+
+[animation]

docs/source/user/documents_kernels.md

@@ -0,0 +1,24 @@
+
+## Kernel backed documents
+
+In the Jupyter architecture, Kernels are separate processes started by the
+server that run your code in different programming languages. JupyterLab allows
+you to connect any open text file to a code console/kernel. With this, you can
+run code from the text file in the kernel interactively.
+
+Right-click on the document and select “Create Console for Editor”: 
+
+[animation]
+
+Once the code console is open, send a single line of code or a seletion of code
+to the code console by hitting `Shift Enter`:
+
+[animation]
+
+In a markdown document, `Shift Enter` will automatically detect if the cursor is
+within a code block, and run the entire block:
+
+[animation]
+
+It is important to emphasize that any text file (markdown, python, R, LaTeX,
+C++, etc.) can be connected to a code console/kernel in this manner.

docs/source/user/extensions.md

@@ -0,0 +1,165 @@
+# Extensions
+
+JupyterLab extensions add functionality to the JupyterLab application. They can
+provide new file viewer types, launcher activities, and output renderers for
+example. JupyterLab extensions are [NPM](https://www.npmjs.com/) packages.
+
+## Installing Node.js
+
+Installing JupyterLab extensions requires Node.js version 4+.
+
+If you use ``conda``, you can get them with:
+
+```bash
+conda -c conda-forge install nodejs
+```
+
+If you use [Homebrew](http://brew.sh/) on Mac OS X:
+
+```bash
+brew install node
+```
+
+## Installing Extensions
+
+The base JupyterLab application includes a core set of extensions, which provide
+the features described in this User Guide (Notebook, Terminal, Text Editor,
+etc.)  New extensions can be installed into the application using the command:
+
+```
+jupyter labextension install <foo>
+```
+
+Where `<foo>` is a valid JupyterLab extension specifier.  This specifier is
+defined by the extension author in their installation instructions. We are
+encouraging extension authors to add the `jupyterlab-extensions` GitHub topic to
+any repository with a JupyterLab extension. You can see a list of extensions by
+[searching Github for the juputerlab-extensions
+topic](https://github.com/search?utf8=%E2%9C%93&q=topic%3Ajupyterlab-extensions&type=Repositories)
+
+List the currently installed extensions by running the command:
+
+```
+jupyter labextension list
+```
+
+Uninstalled an extension by running the command:
+
+```
+jupyter labextension uninstall <bar>
+```
+
+Where `<bar>` is the name of the extension, as printed in the extension list.
+Core extensions can also be uninstalled this way (and can later be
+re-installed).
+
+Disable an extension (without unistalilng it) by running the command:
+
+```
+jupyter labextension disable <foo>
+```
+
+Where `<foo>` is the name of the extension.  This will prevent the extension
+from loading on the front end, but does not require a rebuild. Re-enabled the
+extension later using the command:
+
+```
+jupyter labextension enable <foo>
+```
+
+Core plugins can also be disabled (and then re-enabled).
+
+
+## Advanced usage
+
+The JupyterLab application directory (where the application assets are built and
+the settings reside) can be overridden using `--app-dir` in any of the
+JupyterLab commands, or by setting the `JUPYTERLAB_DIR` environment variable.
+If not specified, it will default to `<sys-prefix/share/jupyter/lab`, where
+`sys-prefix` is the site-specific directory prefix of the current Python
+environment.  You can query the current application path using `jupyter lab
+path`.
+
+To create the app directory without installing any extensions, run `jupyter lab
+build`. The `install` and `link` commands already run the build, so it typically
+does not need to be called directly.
+
+Building consists of:
+
+- Populating the `staging/` directory using template files
+- Handling any linked packages (see `jupyter labextension link`)
+- Ensuring all install assets are available
+- Building the assets
+- Copying the assets to the `static` directory
+
+The `settings` directory contains `page_config.json` and `build_config.json`
+files.
+
+### `page_config.json`
+
+The `page_config.json` data is used to provide config data to the application
+environment.
+
+Two important fields in the `page_config.json` file allow control of which
+plugins load:
+
+1. `disabledExtensions` for extensions that should not load at all.
+2. `deferredExtensions` for extensions that do not load until they are required
+   by something, irrespective of whether they set `autostart` to `true`.
+
+The values for each are an array of strings. The following sequence of checks
+are performed against the patterns in `disabledExtensions` and
+`deferredExtensions`.
+
+* If an identical string match occurs between a config value and a package name
+  (*e.g.*, `"@jupyterlab/apputils-extension"`), then the entire package is
+  disabled (or deferred).
+* If the string value is compiled as a regular expression and tests positive
+  against a package name (*e.g.*, `"disabledExtensions":
+  ["@jupyterlab/apputils*$"]`), then the entire package is disabled (or
+  deferred).
+* If an identical string match occurs between a config value and an individual
+  plugin ID within a larger package (*e.g.*, `"disabledExtensions":
+  ["@jupyterlab/apputils-extension:settings"]`), then that specific plugin is
+  disabled (or deferred).
+* If the string value is compiled as a regular expression and tests positive
+  against an individual plugin ID within a larger package (*e.g.*,
+  `"disabledExtensions": ["^@jupyterlab/apputils-extension:set.*$"]`), then that
+  specific plugin is disabled (or deferred).
+
+### `build_config.json`
+
+The `build_config.json` file is used to track the folders that have been added
+using `jupyter labextension link <folder>`, as well as core extensions that have
+been explicitly uninstalled.  e.g.
+
+```bash
+$ cat settings/build_config.json
+{
+    "uninstalled_core_extensions": [
+        "@jupyterlab/markdownwidget-extension"
+    ],
+    "linked_packages": {
+        "@jupyterlab/python-tests": "/path/to/my/extension"
+    }
+}
+```
+
+The other folders in the app directory are: `extensions`, `static`, and
+`staging`.  The `extensions` folder has the packed tarballs for each of the
+installed extensions for the app.  If the application directory is not the same
+as the `sys-prefix` directory, the extensions installed in the `sys-prefix`
+directory will be used in the app directory.  If an extension is installed in
+the app directory that exists in the `sys-prefix` directory, it will shadow the
+`sys-prefix` version.  Uninstalling an extension will first uninstall the
+shadowed extension, and then attempt to uninstall the `sys-prefix` version if
+called again.  If the `sys-prefix` version cannot be uninstalled, its plugins
+can still be ignored using `ignoredPackages` metadata in `settings`.
+
+The `static` folder contains the assets that will be loaded by the JuptyerLab
+application.  The `staging` folder is used to create the build and then populate
+the `static` folder.
+
+Running `jupyter lab` will attempt to run the `static` assets in the application
+folder if they exist.  You can run `jupyter lab --core-mode` to load the core
+JupyterLab application instead.

docs/source/user/file_editor.md

@@ -0,0 +1,23 @@
+
+# File Editor
+
+The File Editor in JupyterLab enables you to edit text files in JupyterLab:
+
+[screenshot]
+
+The File Editor includes syntax highlighting, configurable indentation (tabs,
+spaces), different key maps (vim, emacs, Sublime Text) and basic theming. These
+settings can be found in the Settings menu:
+
+[screenshot]
+
+To edit an existing text file, double-click on the file in the File Browser or
+drag it into the Dock Panel:
+
+[animation]
+
+To create a new text file in the current directory of the File Browser, click
+the + button at the top of the File Browser and click the “Text Editor” card in
+the Launcher:
+
+[animation]

docs/source/user/file_formats.md

@@ -0,0 +1,196 @@
+
+# File and output formats
+
+## Overview
+
+When working with code and data, you will encounter data and files in a wide
+variety of formats. JupyterLab provides a unified architecture for working with
+data. This model applies whether the data is in a file, or is provided by a
+Kernel as output in a notebook or code console.
+
+For files, the data format is detected by the extension of the file. A single
+file extension may have multiple editors or viewers registered. For example a
+Markdown file (`.md`) can be edited in the File Editor, or rendered inline.
+
+You can access different editors and viewers for a file, by right-clicking on
+the filename in the File Browser and using the "Open With..." submenu:
+
+[screenshot]
+
+To use these different data formats as output in the Notebook or Code Console,
+you can use the relevant display API for the kernel you are using. For example,
+the IPython kernel provides a `display` function that takes a `dict` of keys
+(MIME types) and value (MIME data):
+
+```python
+from IPython.display import display
+display({'text/html': '<h1>Hello World</h1>'}, raw=True)
+```
+
+Running this code will display the HTML in the output of the notebook or code
+console:
+
+[screenshot]
+
+Other Jupyter Kernels offer similar APIs.
+
+## Markdown
+
+* File format: `.md`
+* MIME type: `text/markdown`
+
+Markdown is a simple and popular markup language used for text cells in the
+Jupyter Notebook.
+
+Markdown documents can be edited as text files or rendered inline:
+
+[animation]
+
+The markdown syntax supported in this mode is the same as that in the Jupyter
+Notebook (LaTeX equations work). As seen in the animation, edits to the markdown
+source are immediately reflected in the rendered version:
+
+## Images
+
+* File format: `.png`, `.jpeg`, `.gif`
+* MIME type: `image/png`, `image/jpeg`, `image/gif`
+
+JupyterLab supports image data as files and output in the above formats.
+
+## HTML
+
+* File format: edit as text file
+* MIME type: `text/html`
+
+JupyterLab supports rendered HTML in output. HTML files can be edited as text
+files in the File Editor.
+
+## SVG
+
+* File format: `.svg`
+* MIME type: `image/svg+xml`
+
+JupyterLab will render Scalable Vector Graphics (SVG) in files and output. SVG
+files can slso be edited as text files in the File Editor.
+
+## LaTeX
+
+* File format: edit as text file
+* MIME type: `text/latex`
+
+JupyterLab will render LaTeX questions in output, and LaTeX files (`.tex`) can
+be edited as text files in the File Editor.
+
+## JSON
+
+* File format: `.json`
+* MIME type: `application+json`
+
+JavaScript Object Notation (JSON) files are common in data science.
+
+The default viewer for JSON files is a searchable tree view:
+
+[animation]
+
+To edit the JSON as a text file, right-click on the file in the File Browser and
+select the “Editor” item in the “Open With…” submenu:
+
+[animation]
+
+## CSV
+
+* File format: `.csv`
+* MIME type: None
+
+Files with rows of Comma Separate Values (with a `.csv` extension) are a common
+format for tabular data.
+
+The default viewer for CSV files in JupyterLab is a high performance data grid
+viewer. To view a CSV file in the interactive Data Grid, double-click on the
+file in the File Browser:
+
+[animation]
+
+To edit a CSV file as a text file, right-click on the file in the File Browser
+and select the “Editor” item in the “Open With…” submenu:
+
+[animation]
+
+## PDF
+
+* File format: `.pdf`
+* MIME type: `application/pdf`
+
+PDF files (`.pdf` extension) are a common and standard file format for
+documents. To view a PDF file in JupyterLab, double-click on the file in the
+File Browser:
+
+[animation]
+
+
+## Vega/Vega-Lite
+
+Vega:
+
+* File format: `.vg`, `.vg.json`
+* MIME type: `application/vnd.vega.v2+json`
+
+Vega-Lite:
+
+* File format: `.vl`, `.vl.json`
+* MIME type: `application/vnd.vegalite.v1+json`
+
+Vega and Vega-Lite are declarative visualization grammars that allow
+visualizations to be encoded as JSON data. Fro more information see the
+documentation of Vega or Vega-Lite. JupyterLab has built-in rendering support
+for Vega 2.x and Vega-Lite 1.x data. This support works for both files and
+output in the Notebook and Code Console.
+
+Vega-Lite 1.x files, with a `.vl` or `.vl.json` file extension, can be opened by
+double-clicking he file in the File Browser:
+
+[animation]
+
+The files can also be opened in the JSON viewer or File Editor through the “Open
+With…” submenu in the File Browser content menu:
+
+[animation]
+
+As with other files in JupyterLab multiple views of a single file remain
+synchronized, allowing you to interactively edit and render Vega-Lite/Vega
+visualizations:
+
+[animation]
+
+The same workflow also works for Vega 2.x files, with a `.vg` or `.vg.json` file
+extension.
+
+Output support for Vega/Vega-Lite in the Notebook or Code Console is provided
+through third party libraries such as Altair (Python), the vegalite R package,
+or Vegas (Scala/Spark).
+
+[screenshot]
+
+A JupyterLab extension that supports Vega 3.x and Vega-Lite 2.x can be found
+[here](https://github.com/jupyterlab/jupyter-renderers).
+
+## Virtual DOM
+
+* File format: `.vdom`, `.json`
+* MIME type: `application/vdom.v1+json`
+
+Virtual DOM libraries such as [react.js](https://reactjs.org/) have greatly
+improved the experience of rendering interactive content in HTML. The nteract
+project, which collaborates closely with Project Jupyter, has created a
+[declarative JSON format](https://github.com/nteract/vdom) for virtual DOM data.
+JupyterLab can render this data using react.js. This works for both VDOM files
+with the `.vdom` extension, or within notebook output.
+
+Here is an example of a `.vdom` files being edited and rendered interactively:
+
+[animation]
+
+The [nteract/vdom](https://github.com/nteract/vdom) library provides a Python
+API for creating VDOM output that is rendered in nteract and JupyterLab:
+
+[screenshot or animation]

docs/source/user/files.md

@@ -0,0 +1,76 @@
+
+# Working with files
+
+## Overview
+
+The File Browser and File menu allow you to work with files and directories on
+your system. This includes opening, creating, deleting, renaming, downloading,
+copying and sharing files and directories.
+
+The File Browser is in the Left Panel (the Files tab):
+
+[screenshot]
+
+Many actions on files can also be carried out in the File menu:
+
+[screenshot]
+
+To open any file double-click on its name in the File Browser:
+
+[animation]
+
+You can also drag a file into the Dock Panel:
+
+[animation]
+
+Many files types have multiple viewers/editors. For example, you can open a
+markdown file in the text editor, or as rendered markdown. To open a file in a
+non-default viewer/editor, right-click on its name in the File Browser, and use
+the "Open With..." submenu to select the viewer/editor:
+
+[animation]
+
+A single file can be open simultaneously in multiple viewer/editors and they
+will remain in sync:
+
+[animation]
+
+The file system can be navigated by double clicking on folders, or on the
+directories at the top of the directory listing:
+
+[animation]
+
+Each file or directory in JupyterLab also has a URL that can used to open
+JupyterLab with that file or directory open. To get the shareable link,
+right-click on the file or directory and select the "Copy Shareable Link" item:
+
+[screenshot]
+
+## Creating files and activities
+
+Create new files or activities by clicking the + button at the top of the File
+Browser. This will open the Launcher in the Dock Panel, which allows you to pick
+an activity and kernel:
+
+[animation]
+
+You can also create new documents or activities using the File Menu:
+
+[screenshot]
+
+The current working directory of the Launcher will follow that of the File
+Browser:
+
+[animation]
+
+## Uploading and downloading
+
+Files can be uploaded to the current directory of the File Browser by dragging
+and dropping files onto the File Browser:
+
+[animation]
+
+Any file in JupyterLab can be downloaded by clicking on the “Download” button at
+the top of the File Browser:
+
+[animation]

docs/source/user/interface.md

@@ -0,0 +1,96 @@
+
+# The Interface
+
+The JupyterLab provides the flexible building blocks for interactive,
+exploratory computing. While JupyterLab has many features found in traditional
+IDEs (Integrated Development Environments), it remains focused on interactive,
+exploratory computing.
+
+The JupyterLab Interface consists of a Menu Bar at the top, with a Left Panel
+and Dock Panel below. The Left Panel contains the File Browser, the Running
+List, the Command Palette, the Cell Tools Inspector and the Tabs List. The main
+work area for documents in JupyterLab is called the Dock Panel.
+
+[screenshot]
+
+## Menu Bar
+
+The Menu Bar at the top of JupyterLab has top-level menus that expose all of the
+actions available in JupyterLab, along with showing their keyboard shortcuts.
+The default menus are:
+
+
+- File: actions related to files and directories
+- Edit: actions related to editing documents and other activities
+- View: actions that reversibly alter the appearance of JupyterLab
+- Run: actions for running code in different activities such as Notebooks and
+  Code Consoles
+- Kernel: actions for managing Kernels, which are separately processes which run
+  code
+- Tabs: a list of the open documents and activities in the Dock Panel
+- Settings: common settings and an advanced Settings Editor
+- Help: a list of JupyterLab and Kernel related help links
+
+JupyterLab extensions can also create new top-level menus in the Menu Bar.
+
+## Left Panel
+
+The Left Panel contains a number of commonly used panels, such as the File
+Browser, Running List, Command Palette and Tabs List:
+
+[screenshot]
+
+The Left Panel can be collapsed or expanded by clicking on the active tab:
+
+[animation]
+
+JupyterLab extensions can add additional panels to the Left Panel.
+
+## Dock Panel
+
+The Dock Panel is the main work area in JupyterLab and allows you to arrange
+documents (notebooks, text files, etc.) and other activities (terminals, code
+consoles, etc.) into panels and tabs that can be resized or subdivided:
+
+[animation]
+
+The Dock Panel has a single active document or activity that receives keyboard
+focus and whose tab is marked with a colored top border (blue by default):
+
+[screenshot]
+
+## Tabs and single-document view
+
+The Tabs List gives you access to the open documents and activities in the Dock
+Panel:
+
+[screenshot]
+
+The same information is also available in the Tab Menu:
+
+[screenshot]
+
+It is often useful to focus your work on a single document, while not closing
+other documents. Single Document Mode toggles the view of the Dock Panel to show
+only a single document at a time:
+
+[animation]
+
+When you leave Single Document Mode, the original layout of the Dock Panel is
+restored:
+
+[animation]
+
+
+## Context Menus
+
+Many parts of JupyterLab, such as notebooks, text files, code consoles, Dock
+Panel tabs, etc. have context menus that can be accessed by right-clicking on
+the element:
+
+[animation]
+
+The browser’s native context menu can be accessed by holding down `Shift` and
+right-clicking:
+
+[animation]

docs/source/user/notebook.md

@@ -0,0 +1,55 @@
+
+# Notebooks
+
+Jupyter Notebooks are documents that combine live runnable code, with narrative
+text (markdown), equations (LaTeX), images, interactive visualizations and other
+rich output:
+
+[screenshot]
+
+**Jupyter Notebook (.ipynb files) are fully supported in JupyterLab.**
+Furthermore, the [notebook document
+format](http://nbformat.readthedocs.io/en/latest/) used in JupyterLab is the
+same as the classic notebook. Thus, your existing notebooks should work fine in
+JupyterLab. If they don’t, please open an issue on our [GitHub
+issues](https://github.com/jupyterlab/jupyterlab/issues) page.
+
+Create a notebook by clicking the + button in the File Browser and then
+selecting a kernel:
+
+The user interface for Notebooks in JupyterLab closely follows that of the
+classic Jupyter Notebook. The keyboard shortcuts of the classic Notebook
+continue to work (with command and edit mode). However, a number of new things
+are possible with notebooks in JupyterLab.
+
+Drag and drop cells to rearrange your notebook:
+
+[animation]
+
+Drag cells between notebooks to quickly copy content:
+
+[animation]
+
+Create multiple, synchronized views of a single notebook:
+
+[animation]
+
+Collapse and expand code and output using the View Menu or the blue collapser
+button on left of each cell:
+
+[animation]
+
+Create a new, synchronized view of a cell’s output:
+
+[animation]
+
+Tab completion (activated with the `Tab` key) now includes additional
+information about the types of the matched items:
+
+[animation]
+
+The tooltip (activated with `Shift Tab`) contains additional information about
+objects:
+
+[animation]
+

docs/source/user/running.md

@@ -0,0 +1,19 @@
+# Running kernels and terminals
+
+The Running List (Running tab in the Left Panel) shows a list of all the
+notebooks, code consoles and terminals that are currently running across all
+directories:
+
+[screenshot]
+
+As with the classic Jupyter Notebook, when you close a notebook document, code
+console or terminal, the underlying kernel or terminal running on the server
+continues to run. This allows you to perform long running actions and return
+later. The Running List allows you to re-open, or focus, the document linked to
+a given Kernel or Terminal:
+
+[animation]
+
+Kernels or Terminals can be shutdown from the Running list:
+
+[animation]

docs/source/user/terminal.md

@@ -0,0 +1,21 @@
+
+# Terminals
+
+JupyterLab Terminals provide full support for system shells (bash, tsch, etc.)
+on Mac/Linux and Command.exe on Windows. With the Terminal, you can run anything
+in your system shell, including programs such as vim or emacs. The Terminals run
+on the system where the Jupyter server is running, with the permissions of your
+user. Thus, if JupyterLab is installed on your local machine, the JupyterLab
+terminals will run there.
+
+[screenshot]
+
+To open a new Terminal click the + button in the File Browser and select the
+Terminal in the Launcher:
+
+[animation]
+
+Closing a terminal will leave it running on the server, but you can re-open it
+using the Running Tab:
+
+[animation]

docs/virtualdom.md

@@ -1,76 +0,0 @@
-# Virtual DOM
-
-JupyterLab is based on [PhosphorJS](http://phosphorjs.github.io/), which
-provides a flexible `Widget` class that handles the following:
-
-* Resize events that propagate down the Widget heirarchy.
-* Lifecycle events (`onBeforeDetach`, `onAfterAttach`, etc.).
-* Both CSS-based and absolutely postioned layouts.
-
-The idea of virtual DOM rendering, which became popular in the
-[ReactJS](https://facebook.github.io/react/) community, is a very elegant
-and efficient way of rendering and updating DOM content in response to
-model/state changes. The base `Widget` class in PhosphorJS does not use virtual
-DOM rendering, however Phosphor provides a lightweight virtual DOM API that can
-be used to render leaf content inside a `Widget`. However, the virtual DOM
-API in PhosphorJS is implemented in a manner that is unopinionated about how
-it is used.
-
-In JupyterLab, we provide a more opinionated API for using virtual DOM
-rendering following best practices. This API can be found in `common/vdom.ts`
-and offers two classes:
-
-* `VDomModel`
-* `VDomRenderer`
-
-To use these classes, we recommend the following approach.
-
-First, import the virtual DOM API from PhosphorJS and JupyterLab:
-
-```typescript
-import {
-  h, VNode
-} from 'phosphor/lib/ui/vdom';
-
-import {
-  VDomModel, VDomRenderer
-} from '../common/vdom'; // From another JupyterLab plugin
-```
-
-Second, create a subclass of `VDomModel` that contains all of the state needed
-to render the content:
-
-```typescript
-class TestModel extends VDomModel {
-  get myvalue(): string {
-    return this._myvalue;
-  }
-
-  set myvalue(newValue: string) {
-    this._myvalue = newValue;
-    this.stateChanged.emit(void 0);
-  }
-
-  private _myvalue = '';
-}
-```
-
-For each attribute that is part of your model, you will implement a `get` and `set`
-method as we have done here for the `myvalue` attribute. All of the `set` methods
-in your model should end by calling `this.stateChanged.emit(void 0)`.
-
-Third, create a subclass of `VDomRenderer` that has a `render()` method that uses Phosphor's
-virtual DOM API and returns a PhosphorJS `VNode` or an array of them:
-
-```typescript
-class TestWidget extends VDomRenderer<TestModel> {
-  protected render(): VNode | VNode[] {
-    return h.span(this.model.myvalue);
-  } 
-}
-```
-
-Now anytime the model is changed, the content will be rendered on the page efficiently using the virtual
-DOM approach.
-
-

jupyterlab/tests/test_app.py

@@ -98,7 +98,7 @@ class _test_env(object):
         self.stop()
 
 
-class TestApp(ProcessApp):
+class ProcessTestApp(ProcessApp):
     """A process app for running tests, includes a mock contents directory.
     """
     notebook_dir = Unicode(_create_notebook_dir())
@@ -129,7 +129,7 @@ class TestApp(ProcessApp):
             os._exit(1)
 
 
-class KarmaTestApp(TestApp):
+class KarmaTestApp(ProcessTestApp):
     """A notebook app that runs the jupyterlab karma tests.
     """
     karma_pattern = Unicode('src/*.spec.ts')

packages/services/test/run-test.py

@@ -9,13 +9,13 @@ import os
 
 from traitlets import Bool
 
-from jupyterlab.tests.test_app import TestApp
+from jupyterlab.tests.test_app import ProcessTestApp
 
 
 HERE = os.path.dirname(os.path.realpath(__file__))
 
 
-class ServicesTestApp(TestApp):
+class ServicesTestApp(ProcessTestApp):
     """A notebook app that runs a mocha test."""
 
     coverage = Bool(False, help='Whether to run coverage')