Browse Source

Delete outdated information on packaging extensions

Also, other light editing.
Jason Grout 4 years ago
parent
commit
c0316e3eaa
1 changed files with 13 additions and 41 deletions
  1. 13 41
      docs/source/extension/extension_dev.rst

+ 13 - 41
docs/source/extension/extension_dev.rst

@@ -537,54 +537,23 @@ Serving a prebuilt extension
 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.
 
 
-Packaging extensions
---------------------
-
-Most extensions are single JavaScript packages, and can be shipped on npmjs.org.
-This makes them discoverable by the JupyterLab extension manager, provided they
-have the ``jupyterlab-extension`` keyword  in their ``package.json``.  If the package also
-contains a server extension (Python package), the author has two options.
-The server extension and the JupyterLab extension can be shipped in a single package,
-or they can be shipped separately.
-
-The JupyterLab extension can be bundled in a package on PyPI and conda-forge so
-that it ends up in the user's application directory.  Note that the user will still have to run ``jupyter lab build``
-(or build when prompted in the UI) in order to use the extension.
-The general idea is to pack the Jupyterlab extension using ``npm pack``, and then
-use the ``data_files`` logic in ``setup.py`` to ensure the file ends up in the
-``<jupyterlab_application>/share/jupyter/lab/extensions``
-directory.
-
-Note that even if the JupyterLab extension is unusable without the
-server extension, as long as you use the companion package metadata it is still
-useful to publish it to npmjs.org so it is discoverable by the JupyterLab extension manager.
-
-The server extension can be enabled on install by using ``data_files``.
-an example of this approach is `jupyterlab-matplotlib <https://github.com/matplotlib/jupyter-matplotlib/tree/ce9cc91e52065d33e57c3265282640f2aa44e08f>`__.  The file used to enable the server extension is `here <https://github.com/matplotlib/jupyter-matplotlib/blob/ce9cc91e52065d33e57c3265282640f2aa44e08f/jupyter-matplotlib.json>`__.   The logic to ship the JS tarball and server extension
-enabler is in `setup.py <https://github.com/matplotlib/jupyter-matplotlib/blob/ce9cc91e52065d33e57c3265282640f2aa44e08f/setup.py>`__.  Note that the ``setup.py``
-file has additional logic to automatically create the JS tarball as part of the
-release process, but this could also be done manually.
-
-
-
-
-
-
 Runtime configuration
 ---------------------
-- We handle disabling of lab extensions using a trait on the ``LabApp`` class, so it can be set by admins and overridden by users.  Extensions are automatically enabled when installed, and must be explicitly disabled.  The disabled config can consist of a package name or a plugin regex pattern
-- ``page_config`` and ``overrides`` are also handled with traits so that admins can provide defaults and users can provide overrides
 
+- We handle disabling of lab extensions using a trait on the ``LabApp`` class,
+so it can be set by admins and overridden by users.  Extensions are
+automatically enabled when installed, and must be explicitly disabled.  The
+disabled config can consist of a package name or a plugin regex pattern
+- ``page_config`` and ``overrides`` are also handled with traits so that
+admins can provide defaults and users can provide overrides
 
 
+Development workflow for source extensions
+------------------------------------------
 
-Development workflow
---------------------
-
-We encourage extension authors to add the `jupyterlab-extension GitHub topic
-<https://github.com/search?utf8=%E2%9C%93&q=topic%3Ajupyterlab-extension&type=Repositories>`__ to any GitHub extension repository.
+Developing prebuilt extensions is usually much easier since they do not require rebuilding JupyterLab to see changes. If you need to develop a source extension, here are some tips for a development workflow.
 
-While authoring the extension, you can use the command:
+While authoring a source extension, you can use the command:
 
 .. code-block:: bash
 
@@ -692,6 +661,9 @@ path on the user's machine or a provided tarball. Any valid
 ``jupyter labextension install`` (e.g. ``foo@latest``, ``bar@3.0.0.0``,
 ``path/to/folder``, and ``path/to/tar.gz``).
 
+We encourage extension authors to add the `jupyterlab-extension GitHub topic
+<https://github.com/search?utf8=%E2%9C%93&q=topic%3Ajupyterlab-extension&type=Repositories>`__ to any GitHub extension repository.
+
 Testing your extension
 ^^^^^^^^^^^^^^^^^^^^^^