More editing

docs/source/extension/extension_dev.rst

@@ -401,6 +401,13 @@ 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:
+
+.. code-block:: json
+
+   "jupyterlab": {
+     "outputDir": "mypackage/labextension"
+   }
 
 .. _webpackConfig:
 
@@ -408,27 +415,18 @@ Custom webpack config
 """""""""""""""""""""
 
 .. warning::
-   This feature is *experimental*, as it makes it possible to override the base config used by the prebuilt extension builder.
-
-   It also exposes the internals of the prebuilt extension build system (namely ``webpack``) to extension authors, which was until now kept as an implementation detail.
+   This feature is *experimental* and may change without notice since it exposes internal implementation details (namely ``webpack``). Be careful in using it, as a misconfiguration may break the prebuilt extension system.
 
-The prebuilt extension system uses ``webpack`` to build federated extensions, relying on the
-`Module Federation System <https://webpack.js.org/concepts/module-federation/>`_ added in webpack 5.
+The prebuilt extension system uses ``webpack`` to build extensions, relying on the
+`Module Federation System <https://webpack.js.org/concepts/module-federation/>`_ added in webpack 5. Normally this is an implementation detail that prebuilt extension authors do not need to worry about, but occasionally extension authors will want to tweak the configuration used to build their extension to enable various webpack features. Extension authors can specify a custom webpack config file that will be merged with the webpack config generated by the prebuilt extension system using the ``jupyterlab.webpackConfig`` field in ``package.json``. The value should be the relative path to the config file:
 
-To specify a custom webpack config to the federated extension build system, extension authors can add the ``webpackConfig`` subkey to the
-``package.json`` of their extension::
+.. code-block:: json
 
     "jupyterlab": {
-      "webpackConfig": "webpack.config.js"
+      "webpackConfig": "./webpack.config.js"
     }
 
-The webpack config file can be placed in a different location with a custom name::
-
-    "jupyterlab": {
-      "webpackConfig": "./config/test-config.js"
-    }
-
-Here is an example of a custom config that enables the async WebAssembly and top-level ``await`` experiments:
+Here is an example of a ``webpack.config.js`` custom config that enables the async WebAssembly and top-level ``await`` experimental features of webpack:
 
 .. code-block:: javascript
 
@@ -439,13 +437,23 @@ Here is an example of a custom config that enables the async WebAssembly and top
       }
     };
 
-This custom config will be merged with the `default config <https://github.com/jupyterlab/jupyterlab/blob/master/builder/src/webpack.config.base.ts>`_
-when building the federated extension with ``jlpm run build``.
+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), there is an extra file, ``install.json`` that helps the user know how a prebuilt extension was installed. This file is put there by the packaging system distributing the prebuilt extension.
+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.
 
 Steps for building
 ^^^^^^^^^^^^^^^^^^