Merge pull request #2221 from blink1073/fix

Clean up jupyter lab build help and add to travis tests

.travis.yml

@@ -12,6 +12,7 @@ env:
   matrix:
     - GROUP=tests
     - GROUP=coverage_and_docs
+    - GROUP=cli
   global:
   - GH_REF: github.com/jupyterlab/jupyterlab.git
   - secure: MWpTI6cj3/Bnmtrr0Oqlp2JeWqDneB9aEjlQDaRxLOkqVbxhqDcYW9qAgZZP+sq29vT5oVMWzyCirteKxJfG2vy3HQE1XNLhz82Sf/7sE6DQ51gohl0CcOeA/uA8hCXEw97hneFWsZgHKqSoch7nVDsE3qfYgO+930jHlnxYApJGP9hZFv2Q2NVa6+99kipEYS4BY/yBDYKy6/t4kXcnBrUlNaPtdjnXcrY9esLZ7EQtkaG5VqcQVIBaLJKGF5Q7Aufj5nCFaZ6hZDF1Bi/AbmIbVWFyiT+22i8DZK6YwenECckyzoWkl+bEhYepWsgBKh/BDgPBAmPWKHgU5V4apDaGqZBhF7FP6H02AdZYYuCwl47jyakqvWLZW7oDmorL+HsWG5HQ3m0tMT2ywdbwNOiD39tiPPXjsvROh5ys9vL6NzQvxILCeEOnzcZrFuxi2LGEZfnlqRIjkh1llUAvNc3mOycRLWDOwVQa2+U59qDRXCSY2RD+MOfcdFUGengVujTMaAPMBUa3E33/ZIOOKJtR5TIajYZvd9B2uDlz02QfvTK+hrTaNYJjRZ8WCaeSM/CIKdoLw+29MNO6eqtchw0/vNvM8c9EkhrhMQKcY04OecVhmZkemFhd4SD5l92VX3z3xSxLkmazfNkj3CigWDXNxfDd2ORoGjA46Pga8RM=

CONTRIBUTING.md

@@ -194,6 +194,9 @@ the core application in `<git root>/jupyterlab/build`,
 run `jupyter lab --core-mode`.  This is the core application that will
 be shipped.
 
+- If working with extensions, see the extension documentation on
+https://jupyterlab-tutorial.readthedocs.io/en/latest/index.html.
+
 - The npm modules are fully compatible with Node/Babel/ES6/ES5. Simply
 omit the type declarations when using a language other than TypeScript.
 

docs/extensions_dev.md

@@ -82,8 +82,8 @@ jupyter labextension link <path>
 ```
 
 This causes the builder to re-install the source folder before building
-the application files.  You can also link other npm packages that
-you are working on simultaneously; they will be re-installed but not
+the application files.  You can re-build at any time using `jupyter lab build` and it will reinstall these packages.  You can also link other npm packages 
+that you are working on simultaneously; they will be re-installed but not
 considered as extensions if they lack the metadata.
 
 You can see the list of linked extensions using:

docs/extensions_user.md

@@ -63,7 +63,18 @@ 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`.
+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.

jupyterlab/commands.py

@@ -8,10 +8,9 @@ import json
 import pipes
 import os
 import glob
-from uuid import uuid4
 from os import path as osp
 from os.path import join as pjoin
-from subprocess import check_output, CalledProcessError
+from subprocess import check_output, CalledProcessError, STDOUT
 import shutil
 import sys
 import tarfile
@@ -42,9 +41,11 @@ def run(cmd, **kwargs):
     print('> ' + list2cmdline(cmd))
     kwargs.setdefault('shell', sys.platform == 'win32')
     kwargs.setdefault('env', os.environ)
+    kwargs.setdefault('stderr', STDOUT)
     try:
         return check_output(cmd, **kwargs)
     except CalledProcessError as error:
+        print(error.output)
         raise error
 
 

jupyterlab/labapp.py

@@ -18,12 +18,17 @@ build_aliases = dict(base_aliases)
 build_aliases['app-dir'] = 'LabBuildApp.app_dir'
 build_aliases['name'] = 'LabBuildApp.name'
 build_aliases['version'] = 'LabBuildApp.version'
-build_aliases['publicPath'] = 'LabBuildApp.publicPath'
 
 
 class LabBuildApp(JupyterApp):
     version = __version__
-    description = "Build the JupyterLab application"
+    description = """
+    Build the JupyterLab application
+
+    The application is built in the JupyterLab app directory in `/staging`.
+    When the build is complete it is put in the JupyterLab app `/static`
+    directory, where it is used to serve the application.
+    """
     aliases = build_aliases
 
     app_dir = Unicode('', config=True,
@@ -45,7 +50,12 @@ clean_aliases['app-dir'] = 'LabCleanApp.app_dir'
 
 class LabCleanApp(JupyterApp):
     version = __version__
-    description = "Clean the JupyterLab application"
+    description = """
+    Clean the JupyterLab application
+
+    This will clean the app directory by removing the `staging` and `static`
+    directories.
+    """
     aliases = clean_aliases
 
     app_dir = Unicode('', config=True,
@@ -57,7 +67,11 @@ class LabCleanApp(JupyterApp):
 
 class LabPathApp(JupyterApp):
     version = __version__
-    description = "Print the configured path to the JupyterLab application"
+    description = """
+    Print the configured path to the JupyterLab application
+
+    The path can be configured using the JUPYTERLAB_DIR environment variable.
+    """
 
     def start(self):
         print(get_app_dir())
@@ -77,10 +91,17 @@ class LabApp(NotebookApp):
     version = __version__
 
     description = """
-        JupyterLab - An extensible computational environment for Jupyter.
+    JupyterLab - An extensible computational environment for Jupyter.
+
+    This launches a Tornado based HTML Server that serves up an
+    HTML5/Javascript JupyterLab client.
+
+    If run in core mode (e.g. `jupyter lab --core-mode`), it will run
+    the shipped JupyterLab application with no installed extensions.
 
-        This launches a Tornado based HTML Server that serves up an
-        HTML5/Javascript JupyterLab client.
+    Otherwise, it will run using the assets in the JupyterLab app
+    directory (found using `jupyter lab path`), if present.
+    If not present, it will fall back to the core application.
     """
 
     examples = """

jupyterlab/labextensions.py

@@ -52,7 +52,14 @@ class InstallLabExtensionApp(BaseExtensionApp):
 
 
 class LinkLabExtensionApp(BaseExtensionApp):
-    description = "Link labextension(s)"
+    description = """
+    Link labextension(s) or packages.
+
+    Links a package to the JupyterLab build process.  If the package is
+    an extension, it will also be installed as an extension.  A linked
+    package is manually re-installed from its source location when
+    `jupyter lab build` is run.
+    """
 
     def start(self):
         self.extra_args = self.extra_args or [os.getcwd()]
@@ -62,7 +69,7 @@ class LinkLabExtensionApp(BaseExtensionApp):
 
 
 class UnlinkLabExtensionApp(BaseExtensionApp):
-    description = "Unlink labextension(s)"
+    description = "Unlink labextension(s) or packages by name or path"
 
     def start(self):
         self.extra_args = self.extra_args or [os.getcwd()]
@@ -73,7 +80,7 @@ class UnlinkLabExtensionApp(BaseExtensionApp):
 
 
 class UninstallLabExtensionApp(BaseExtensionApp):
-    description = "Uninstall labextension(s)"
+    description = "Uninstall labextension(s) by name"
 
     def start(self):
         self.extra_args = self.extra_args or [os.getcwd()]
@@ -84,7 +91,7 @@ class UninstallLabExtensionApp(BaseExtensionApp):
 
 
 class ListLabExtensionsApp(BaseExtensionApp):
-    description = "List the installed labextension"
+    description = "List the installed labextensions"
     should_build = False
 
     def start(self):

scripts/travis_install.sh

@@ -6,7 +6,7 @@ set -x
 
 npm update
 
-if [[ $GROUP == tests ]]; then
+if [[ $GROUP == tests || $GROUP == cli ]]; then
     wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh;
 fi
 

scripts/travis_script.sh

@@ -11,14 +11,6 @@ export PATH="$HOME/miniconda/bin:$PATH"
 
 
 if [[ $GROUP == tests ]]; then
-    # Make sure we can successfully load the core app.
-    pip install selenium
-    python -m jupyterlab.selenium_check --core-mode
-
-    # Make sure we can build and run the app.
-    jupyter lab build
-    python -m jupyterlab.selenium_check 
-    jupyter labextension list
 
     # Run the JS and python tests
     py.test
@@ -65,3 +57,38 @@ if [[ $GROUP == coverage_and_docs ]]; then
     source deactivate
     popd
 fi
+
+
+if [[ $GROUP == cli ]]; then
+    # Make sure we can successfully load the core app.
+    pip install selenium
+    python -m jupyterlab.selenium_check --core-mode
+
+    # Make sure we can build and run the app.
+    jupyter lab build
+    python -m jupyterlab.selenium_check 
+    jupyter labextension list
+
+    # Test the cli apps.
+    jupyter lab clean
+    jupyter lab build
+    jupyter lab path
+    jupyter labextension link jupyterlab/tests/mockextension --no-build
+    jupyter labextension unlink jupyterlab/tests/mockextension --no-build
+    jupyter labextension link jupyterlab/tests/mockextension --no-build
+    jupyter labextension unlink  @jupyterlab/python-tests --no-build
+    jupyter labextension install jupyterlab/tests/mockextension  --no-build
+    jupyter labextension list
+    jupyter labextension uninstall @jupyterlab/python-tests
+
+    # Make sure we can call help on all the cli apps.
+    jupyter lab -h 
+    jupyter lab build -h 
+    jupyter lab clean -h
+    jupyter lab path -h 
+    jupyter labextension link -h
+    jupyter labextension unlink -h
+    jupyter labextension install -h 
+    jupyter labextension uninstall -h 
+    jupyter labextension list -h
+fi