Merge pull request #9546 from jasongrout/docs3fix

Docs updates for 3.0

README.md

@@ -29,13 +29,13 @@ powerful user interface.
 JupyterLab will eventually replace the classic Jupyter Notebook.
 
 JupyterLab can be extended using [npm](https://www.npmjs.com/) packages
-that use our public APIs. To find JupyterLab extensions, search for the npm keyword [jupyterlab-extension](https://www.npmjs.com/search?q=keywords:jupyterlab-extension) or the GitHub topic [jupyterlab-extension](https://github.com/topics/jupyterlab-extension). To learn more about extensions, see the [user documentation](https://jupyterlab.readthedocs.io/en/latest/user/extensions.html).
+that use our public APIs. To find JupyterLab extensions, search for the npm keyword [jupyterlab-extension](https://www.npmjs.com/search?q=keywords:jupyterlab-extension) or the GitHub topic [jupyterlab-extension](https://github.com/topics/jupyterlab-extension). To learn more about extensions, see the [user documentation](https://jupyterlab.readthedocs.io/en/stable/user/extensions.html).
 
 The current JupyterLab releases are suitable for general
 usage, and the extension APIs will continue to
 evolve for JupyterLab extension developers.
 
-Read the latest version's documentation on [ReadTheDocs](http://jupyterlab.readthedocs.io/en/latest/).
+Read the current JupyterLab documentation on [ReadTheDocs](http://jupyterlab.readthedocs.io/en/stable/).
 
 ---
 
@@ -88,19 +88,13 @@ If you encounter an error like "Command 'jupyter' not found", please make sure `
 
 ### Prerequisites and Supported Browsers
 
-Jupyter notebook version 4.3 or later is required. To check the notebook version, run the command:
-
-```bash
-jupyter notebook --version
-```
-
 The latest versions of the following browsers are currently _known to work_:
 
 - Firefox
 - Chrome
 - Safari
 
-See our [documentation](http://jupyterlab.readthedocs.io/en/latest/getting_started/installation.html) for additional details.
+See our [documentation](http://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html) for additional details.
 
 ---
 
@@ -110,7 +104,7 @@ We encourage you to ask questions on the [Discourse forum](https://discourse.jup
 
 ### Bug report
 
-To report a bug please read the [guidelines](https://jupyterlab.readthedocs.io/en/latest/getting_started/issue.html) and then open a [Github issue](https://github.com/jupyterlab/jupyterlab/issues/new?template=bug_report.md). To keep resolved issues self-contained, the [lock bot](https://github.com/apps/lock) will lock closed issues as resolved after a period of inactivity. If related discussion is still needed after an issue is locked, please open a new issue and reference the old issue.
+To report a bug please read the [guidelines](https://jupyterlab.readthedocs.io/en/stable/getting_started/issue.html) and then open a [Github issue](https://github.com/jupyterlab/jupyterlab/issues/new?template=bug_report.md). To keep resolved issues self-contained, the [lock bot](https://github.com/apps/lock) will lock closed issues as resolved after a period of inactivity. If related discussion is still needed after an issue is locked, please open a new issue and reference the old issue.
 
 ### Feature request
 
@@ -120,15 +114,15 @@ We also welcome suggestions for new features as they help make the project more
 
 ## Development
 
-### Contributing
+### Extending JupyterLab
 
-To contribute code or documentation to the project, please read the [contributor documentation](https://jupyterlab.readthedocs.io/en/latest/developer/contributing.html).
+To start developing an extension for JupyterLab, see the [developer documentation](https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html) and the [API docs](https://jupyterlab.readthedocs.io/en/stable/api/).
 
-JupyterLab follows the Jupyter [Community Guides](https://jupyter.readthedocs.io/en/latest/community/content-community.html).
+### Contributing
 
-### Extending JupyterLab
+To contribute code or documentation to JupyterLab itself, please read the [contributor documentation](https://jupyterlab.readthedocs.io/en/latest/developer/contributing.html).
 
-To start developing an extension, see the [developer documentation](https://jupyterlab.readthedocs.io/en/latest/developer/extension_dev.html) and the [API docs](http://jupyterlab.github.io/jupyterlab/index.html).
+JupyterLab follows the Jupyter [Community Guides](https://jupyter.readthedocs.io/en/latest/community/content-community.html).
 
 ### License
 

docs/source/extension/extension_dev.rst

@@ -468,7 +468,7 @@ In addition to the package metadata for source extensions, prebuilt extensions h
 Output Directory
 """"""""""""""""
 
-When JupyterLab builds the prebuilt extension, it creates a JavaScript bundle which can then be copied into the appropriate location. The ``jupyterlab.outputDir`` field gives the relative path to the directory where this JavaScript bundle should be placed:
+When JupyterLab builds the prebuilt extension, it creates a directory of files which can then be copied into the :ref:`appropriate install location <distributing_prebuilt_extensions>`. The ``jupyterlab.outputDir`` field gives the relative path to the directory where these JavaScript and other files should be placed. A copy of the ``package.json`` file with additional build metadata will be put in the ``outputDir`` and the JavaScript and other files that will be served are put into the ``static`` subdirectory.
 
 .. code-block:: json
 
@@ -506,21 +506,6 @@ Custom webpack configuration can be used to enable webpack features, configure a
 This custom config will be merged with the `prebuilt extension config <https://github.com/jupyterlab/jupyterlab/blob/master/builder/src/extensionConfig.ts>`_
 when building the prebuilt extension.
 
-Packaging Information
-^^^^^^^^^^^^^^^^^^^^^
-
-Since prebuilt extensions are distributed in many ways (Python pip packages, conda packages, and potentially in many other packaging systems), packages can include an extra file, ``install.json``, that helps the user know how a prebuilt extension was installed and how to uninstall it. This file is put in the appropriate location by the packaging system distributing the prebuilt extension, and is used by JupyterLab to help a user know how to manage the extension. For example, ``jupyter labextension list`` includes information from this file, and ``jupyter labextension uninstall`` can print helpful uninstall instructions. Here is an example ``install.json`` file::
-
-   {
-     "packageManager": "python",
-     "packageName": "mypackage",
-     "uninstallInstructions": "Use your Python package manager (pip, conda, etc.) to uninstall the package mypackage"
-   }
-
-* ``packageManager``: This is the package manager that was used to install the prebuilt extension, for example, ``python``, ``pip``, ``conda``, ``debian``, ``system administrator``, etc.
-* ``packageName``: This is the package name of the prebuilt extension in the package manager above, which may be different than the package name in ``package.json``.
-* ``uninstallInstructions``: This is a short block of text giving the user instructions for uninstalling the prebuilt extension. For example, it might instruct them to use a system package manager or talk to a system administrator.
-
 .. _prebuilt_dev_workflow:
 
 Developing a prebuilt extension
@@ -538,11 +523,36 @@ If you are developing your prebuilt extension against the JupyterLab source repo
 
 We provide a `cookiecutter <https://github.com/jupyterlab/extension-cookiecutter-ts>`_ that handles all of the scaffolding for an extension author, including the shipping of appropriate data files, so that when the user installs the package, the prebuilt extension ends up in ``share/jupyter/labextensions``
 
+.. _distributing_prebuilt_extensions:
+
+Distributing a prebuilt extension
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Prebuilt extensions can be distributed by any system that can copy the prebuilt assets into an appropriate location where JupyterLab can find them. The `official extension cookiecutter <https://github.com/jupyterlab/extension-cookiecutter-ts>`_ shows how to distribute prebuilt extensions via Python pip or conda packages. A system package manager, or even just an administrative script that copies directories, could be used as well.
+
+To distribute a prebuilt extension, copy its :ref:`output directory <outputDir>` to a location where JupyterLab will find it, typically  ``<sys-prefix>/share/jupyter/labextensions/<package-name>``, where ``<package-name>`` is the JavaScript package name in the ``package.json``. For example, if your JavaScript package name is ``@my-org/my-package``, then the appropriate directory would be ``<sys-prefix>/share/jupyter/labextensions/@my-org/my-package``.
 
-Serving a prebuilt extension
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The JupyterLab server makes the ``static/`` files available via a ``/labextensions/`` server handler. The settings and themes handlers in the server also load settings and themes from the prebuilt extension directories. If a prebuilt extension has the same name as a source extension, the prebuilt extension is preferred.
+
+.. _install.json:
+
+Packaging Information
+"""""""""""""""""""""
+
+Since prebuilt extensions are distributed in many ways (Python pip packages, conda packages, and potentially in many other packaging systems), the prebuilt extension directory can include an extra file, ``install.json``, that helps the user know how a prebuilt extension was installed and how to uninstall it. This file should be copied by the packaging system distributing the prebuilt extension into the top-level directory, for example ``<sys-prefix>/share/jupyter/labextensions/<package-name>/install.json``.
+
+This ``install.json`` file is used by JupyterLab to help a user know how to manage the extension. For example, ``jupyter labextension list`` includes information from this file, and ``jupyter labextension uninstall`` can print helpful uninstall instructions. Here is an example ``install.json`` file::
+
+   {
+     "packageManager": "python",
+     "packageName": "mypackage",
+     "uninstallInstructions": "Use your Python package manager (pip, conda, etc.) to uninstall the package mypackage"
+   }
+
+* ``packageManager``: This is the package manager that was used to install the prebuilt extension, for example, ``python``, ``pip``, ``conda``, ``debian``, ``system administrator``, etc.
+* ``packageName``: This is the package name of the prebuilt extension in the package manager above, which may be different than the package name in ``package.json``.
+* ``uninstallInstructions``: This is a short block of text giving the user instructions for uninstalling the prebuilt extension. For example, it might instruct them to use a system package manager or talk to a system administrator.
 
-A prebuilt extension is copied into a directory such as ``sys-prefix/share/jupyter/labextensions/package-name``. The JupyterLab server makes these files available via a ``/labextensions/`` server handler. The settings and themes handlers in the server also load settings and themes from the prebuilt extension installation directories. If a prebuilt extension has the same name as a source extension, the prebuilt extension is preferred.
 
 
 Development workflow for source extensions

docs/source/getting_started/changelog.rst

@@ -52,6 +52,16 @@ Property inspector moved to right sidebar
 
 The default interface for JupyterLab now has system-wide sidebar panes on the left side and sidebar panels that interact with a specific document (such as the debugger or notebook property inspector) on the right side. As always, you can move panes between the left and right sidebars (right click on the sidebar icon, or change it in Advanced Settings).
 
+Command Palette
+"""""""""""""""
+
+The command palette is now a floating window that appears on top of your JupyterLab workspace. This enables users to quickly invoke a command while keeping the sidebar closed or switching sidebar panels. The command palette can be put back into the sidebar by adjusting the default in Advanced Settings.
+
+Jupyter Server
+""""""""""""""
+
+JupyterLab 3.0 now depends on `Jupyter Server <https://jupyter-server.readthedocs.io>`_, which is a new Jupyter project based on the server portion of the classic Notebook server. See the `Migration Guide <https://jupyter-server.readthedocs.io/en/stable/operators/migrate-from-nbserver.html>`_ to migrate custom notebook configuration to Jupyter Server.
+
 For Developers
 ^^^^^^^^^^^^^^
 

docs/source/getting_started/installation.rst

@@ -66,32 +66,10 @@ Docker
 If you have `Docker installed <https://docs.docker.com/install/>`__, you can install and use JupyterLab by selecting one
 of the many `ready-to-run Docker images <https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html>`__
 maintained by the Jupyter Team. Follow the instructions in the `Quick Start Guide <https://jupyter-docker-stacks.readthedocs.io/en/latest/>`__
-to deploy the chosen Docker image. NOTE: Ensure your docker command includes the `-e JUPYTER_ENABLE_LAB=yes` flag to ensure
-JupyterLab is enabled in your container.
-
-
-
-Installing with Previous Versions of Notebook
----------------------------------------------
-
-If you are using a version of Jupyter Notebook earlier than 5.3, then you must also run the following command to enable the JupyterLab
-server extension:
-
-.. code:: bash
-
-    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:
-
-.. code:: bash
-
-    jupyter notebook --version
+to deploy the chosen Docker image.
 
+Ensure your docker command includes the ``-e JUPYTER_ENABLE_LAB=yes`` flag to ensure
+JupyterLab is enabled in your container.
 
 Usage with JupyterHub
 ---------------------
@@ -119,7 +97,7 @@ A tool like `postcss <https://postcss.org/>`__ can be used to convert the CSS fi
 Usage with private NPM registry
 -------------------------------
 
-To install extensions, you will need access to a NPM packages registry. Some companies do not allow
+To install some extensions, you will need access to an NPM packages registry. Some companies do not allow
 reaching directly public registry and have a private registry. To use it, you need to configure ``npm``
 **and** ``yarn`` to point to that registry (ask your corporate IT department for the correct URL):
 
@@ -128,42 +106,33 @@ reaching directly public registry and have a private registry. To use it, you ne
     npm config set registry https://registry.company.com/
     yarn config set registry https://registry.company.com/
     
-JupyterLab will pick up that registry automatically.
-
-.. note::
+JupyterLab will pick up that registry automatically. You can check which registry URL is used by JupyterLab by running::
 
-    You can check which registry URL is used by JupyterLab by running::
-    
-      python -c "from jupyterlab.commands import AppOptions; print(AppOptions().registry)"
+    python -c "from jupyterlab.commands import AppOptions; print(AppOptions().registry)"
 
 Installation problems
 ---------------------
 
 If your computer is behind corporate proxy or firewall,
-you may encounter HTTP and SSL errors due to custom security profiles managed by corporate IT departments.
-
-Example of typical error, when conda cannot connect to own repositories:
-
-+ `CondaHTTPError: HTTP 000 CONNECTION FAILED for url <https://repo.anaconda.com/pkgs/main/win-64/current_repodata.json>`
+you may encounter HTTP and SSL errors due to the proxy or firewall blocking connections to widely-used servers. For example, you might see this error if conda cannot connect to its own repositories::
 
+    CondaHTTPError: HTTP 000 CONNECTION FAILED for url <https://repo.anaconda.com/pkgs/main/win-64/current_repodata.json>
 
-This may happen because your company can block connections to widely-used repositories in Python and JavaScript communities.
+Here are some widely-used sites that host packages in the Python and JavaScript open-source ecosystems. Your network adminstrator may be able to allow http and https connections to these domains:
 
-Here are some widely-used sites that host packages in the Python and JavaScript open-source ecosystem. Your network adminstrator may be able to allow http and https connections to these:
+- pypi.org
+- pythonhosted.org
+- continuum.io
+- anaconda.com
+- conda.io
+- github.com
+- githubusercontent.com
+- npmjs.com
+- yarnpkg.com
 
-- \*.pypi.org
-- \*.pythonhosted.org
-- \*.continuum.io
-- \*.anaconda.com
-- \*.conda.io
-- \*.github.com
-- \*.githubusercontent.com
-- \*.npmjs.com
-- \*.yarnpkg.com
-
-Alternatively you can specify proxy user (mostly domain user with password),
+Alternatively, you can specify a proxy user (usually a domain user with password),
 that is allowed to communicate via network. This can be easily achieved
-by setting two common environment variables: `HTTP_PROXY` and `HTTPS_PROXY`.
+by setting two common environment variables: ``HTTP_PROXY`` and ``HTTPS_PROXY``.
 These variables are automatically used by many open-source tools (like ``conda``) if set correctly.
 
 .. code:: bash
@@ -176,7 +145,6 @@ These variables are automatically used by many open-source tools (like ``conda``
     export HTTP_PROXY=http://USER:PWD@proxy.company.com:PORT
     export HTTPS_PROXY=https://USER:PWD@proxy.company.com:PORT
 
-
 In case you can communicate via HTTP, but installation with ``conda`` fails
 on connectivity problems to HTTPS servers, you can disable using SSL for ``conda``.
 
@@ -190,7 +158,7 @@ on connectivity problems to HTTPS servers, you can disable using SSL for ``conda
 
 You can do a similar thing for ``pip``.
 The approach here is to mark repository servers as trusted hosts,
-which means, SSL communication will not be required for downloading Python libraries.
+which means SSL communication will not be required for downloading Python libraries.
 
 .. code:: bash
 
@@ -201,12 +169,12 @@ which means, SSL communication will not be required for downloading Python libra
 Using the tips from above, you can handle many network problems 
 related to installing Python libraries.
 
-Many Jupyter extensions require having a working ``npm`` and ``jlpm`` (alias for ``yarn``) commands,
-which is required for downloading useful Jupyter extensions or other JavaScript dependencies.
+Many Jupyter extensions require having working ``npm`` and ``jlpm`` (alias for ``yarn``) commands,
+which is required for downloading useful Jupyter extensions or other JavaScript dependencies. If ``npm`` cannot connect to its own repositories, you might see an error like::
 
-Example of typical error message, when ``npm`` cannot connect to own repositories:
+    ValueError: "@jupyterlab/toc" is not a valid npm package
 
-+ `ValueError: "@jupyterlab/toc" is not a valid npm package`
+You can set the proxy or registry used for npm with the following commands.
 
 .. code:: bash
 
@@ -228,14 +196,3 @@ on connectivity problems to HTTPS servers, you can disable using SSL for ``npm``
 
     # Configure npm to not use SSL
     npm set strict-ssl False
-
-Problems with Extensions and Settings
--------------------------------------
-
-Jupyterlab saves settings via `PUT` requests to the server with a JSON5-compatible payload, even though it claims the PUT request is valid JSON. `JSON5 <https://json5.org/>`__ is a superset of JSON that allows comments, etc. There may be deployment problems, manifest as 400 error return codes when saving settings, if these `PUT` requests are rejected by a routing layer that tries to validate the payload as JSON instead of JSON5.
-
-Common symptoms of this during debugging are:
-
-- The settings are selected but nothing changes, or when extension manager is enabled but the manager tab is not added.
-- JupyterLab's logs don't have the 400 return codes when `PUT` requests are issued.
-- If your JupyterLab logs are on Elastic Search, you'll see `Unexpected token / in JSON at position`. This comes from the JSON5 comments not being valid JSON.

docs/source/getting_started/starting.rst

@@ -19,10 +19,6 @@ into the browser. JupyterLab sessions always reside in a
 
   http(s)://<server:port>/<lab-location>/lab
 
-Because JupyterLab is a server extension of the classic Jupyter Notebook
-server, you can launch JupyterLab by calling ``jupyter notebook``
-and visiting the ``/lab`` URL.
-
 Like the classic notebook,
 JupyterLab provides a way for users to copy URLs that
 :ref:`open a specific notebook or file <url-tree>`. Additionally,
@@ -34,7 +30,6 @@ To open the classic Notebook from JupyterLab, select "Launch Classic Notebook"
 from the JupyterLab Help menu, or you can change the URL
 from ``/lab`` to ``/tree``.
 
-JupyterLab has the same security model as the classic Jupyter Notebook;
-for more information see the `security
-section <https://jupyter-server.readthedocs.io/en/stable/operators/security.html>`__
-of the classic Notebook's documentation.
+JupyterLab runs on top of Jupyter Server, so see the `security
+section <https://jupyter-server.readthedocs.io/en/latest/operators/security.html>`__
+of Jupyter Server's documentation for security-related information.

docs/source/index.rst

@@ -7,7 +7,7 @@
 JupyterLab Documentation
 ########################
 
-JupyterLab is the next-generation web-based user interface for Project Jupyter. `Try it on Binder <https://mybinder.org/v2/gh/jupyterlab/jupyterlab-demo/master?urlpath=lab/tree/demo>`__.  JupyterLab follows the Jupyter `Community Guides <https://jupyter.readthedocs.io/en/latest/community/content-community.html>`__.
+JupyterLab is the next-generation web-based user interface for Project Jupyter. `Try it on Binder <https://mybinder.org/v2/gh/jupyterlab/jupyterlab-demo/3818244?urlpath=lab/tree/demo>`__.  JupyterLab follows the Jupyter `Community Guides <https://jupyter.readthedocs.io/en/latest/community/content-community.html>`__.
 
 .. image:: ./images/jupyterlab.png
    :align: center

docs/source/user/commands.rst

@@ -3,11 +3,10 @@
 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, keyboard shortcuts, etc.). The command palette
-in the left sidebar provides a keyboard-driven way to search for and run
-JupyterLab commands:
+All user actions in JupyterLab are processed through a centralized command
+system. These commands are shared and used throughout JupyterLab (menu bar,
+context menus, keyboard shortcuts, etc.). The command palette provides a
+keyboard-driven way to search for and run JupyterLab commands:
 
 .. image:: images/command_palette.png
    :align: center
@@ -15,11 +14,5 @@ JupyterLab commands:
 
 .. _access-palette:
 
-The command palette can be accessed using the keyboard shortcut
-``Command/Ctrl Shift C``:
-
-.. raw:: html
-
-  <div class="jp-youtube-video">
-     <iframe src="https://www.youtube-nocookie.com/embed/lPuj57UkxYs?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
-  </div>
+The command palette can be accessed from the View menu or using the keyboard shortcut
+``Command/Ctrl Shift C``.

scripts/ci_script.sh

@@ -67,7 +67,7 @@ if [[ $GROUP == linkcheck ]]; then
     # Expire links after a week
     LINKS_EXPIRE=604800
     args="--check-links --check-links-cache --check-links-cache-expire-after ${LINKS_EXPIRE} --check-links-cache-name ${CACHE_DIR}/cache"
-    args="--ignore docs/build/html/genindex.html --ignore docs/build/html/search.html --ignore docs/build/html/api ${args}"
+    args="--ignore docs/build/html/genindex.html --ignore docs/build/html/search.html --ignore docs/build/html/api --ignore docs/build/html/getting_started/changelog.html ${args}"
     py.test $args --links-ext .html -k .html docs/build/html || py.test $args --links-ext .html -k .html --lf docs/build/html
 
     # Run the link check on md files - allow for a link to fail once (--lf means only run last failed)