Document more features for JupyterLab on Binder (jupyterlab#14677)

* Add specific section for configuring Binder

* Include the new file in the toc

Author: fcollonval

docs/source/developer/contributing.rst

@@ -15,11 +15,12 @@ and share what area of the project you are interested in working on. Please also
 Guides <https://jupyter.readthedocs.io/en/latest/community/content-community.html>`__.
 
 You can help make it better by:
-- `submitting bug reports <https://github.com/jupyterlab/jupyterlab/issues/new/choose>`__,
-- `proposing new features <https://github.com/jupyterlab/jupyterlab/issues/new?assignees=&labels=enhancement%2C+status%3ANeeds+Triage&template=feature_request.md>`__,
-- `translating the application <https://crowdin.com/project/jupyterlab>`__,
-- `improving the documentation <https://jupyterlab.readthedocs.io/en/latest>`__,
-- improving the code base and fixing bug (see below)
+
+* `submitting bug reports <https://github.com/jupyterlab/jupyterlab/issues/new/choose>`__,
+* `proposing new features <https://github.com/jupyterlab/jupyterlab/issues/new?assignees=&labels=enhancement%2C+status%3ANeeds+Triage&template=feature_request.md>`__,
+* `translating the application <https://crowdin.com/project/jupyterlab>`__,
+* `improving the documentation <https://jupyterlab.readthedocs.io/en/latest>`__,
+* improving the code base and fixing bug (see below)
 
 
 We have labeled some issues as `good first

docs/source/user/announcements.rst

@@ -43,23 +43,4 @@ using the command line option ``--LabApp.news_url="<URL_TO_FEED_XML_FILE>"``.
 Binder
 ------
 
-To deactivate the announcements on Binder, you can change the default settings.
-To do that, you will need to add those two files in your Binder configuration:
-
-.. code-block:: json
-    :caption: overrides.json
-
-    {
-      "@jupyterlab/apputils-extension:notification": {
-        "fetchNews": "false"
-      }
-    }
-
-.. code-block:: sh
-    :caption: postBuild
-
-    #!/usr/bin/env bash
-    set -eux
-
-    mkdir -p ${NB_PYTHON_PREFIX}/share/jupyter/lab/settings
-    cp overrides.json ${NB_PYTHON_PREFIX}/share/jupyter/lab/settings
+You will find how to deactivate those features on Binder at :ref:`binder`.

docs/source/user/binder.rst

@@ -0,0 +1,58 @@
+.. Copyright (c) Jupyter Development Team.
+.. Distributed under the terms of the Modified BSD License.
+
+.. _binder:
+
+JupyterLab on Binder
+====================
+
+Customize the layout
+--------------------
+
+A specific layout of JupyterLab can be saved as workspace to be restored later or
+to be shared with others.
+
+To specify a workspace on Binder, you first need to export the layout you want to
+use. For that launch JupyterLab and arrange the application in the layout you prefer.
+Then you can export it through the menu ``File -> Save Current Workspace As…``.
+
+Now you need to copy that file in the Binder configuration folder and import it in
+the ``postBuild`` script. Assuming the binder workspace file is stored at ``binder/workspace.jupyterlab-workspace``:
+
+.. code-block:: sh
+    :caption: postBuild
+
+    #!/usr/bin/env bash
+    set -eux
+
+    conda run -n notebook jupyter lab workspaces import --name default binder/workspace.jupyterlab-workspace
+
+Customize user settings
+-----------------------
+
+To customize the user settings on a Binder instance, you can define a ``overrides.json``
+that will contain a dictionary whose primary keys are the plugin ids and the values
+are the new settings.
+
+For example to deactivate the announcements on Binder, you will have to override
+the following setting:
+
+.. code-block:: json
+    :caption: overrides.json
+
+    {
+      "@jupyterlab/apputils-extension:notification": {
+        "fetchNews": "false"
+      }
+    }
+
+Then you will have to copy that file in a special folder:
+
+.. code-block:: sh
+    :caption: postBuild
+
+    #!/usr/bin/env bash
+    set -eux
+
+    mkdir -p ${NB_PYTHON_PREFIX}/share/jupyter/lab/settings
+    cp overrides.json ${NB_PYTHON_PREFIX}/share/jupyter/lab/settings

docs/source/user/index.md

@@ -26,4 +26,5 @@ rtc
 lsp
 interface_customization
 directories
+binder
 ```