Improve language servers configuration documentation

Author: krassowski

docs/Configuring.ipynb

@@ -25,7 +25,7 @@
     "```\n",
     "\n",
     "They will be merged from bottom to top, and the directory where you launch your\n",
-    "`notebook` server wins, making it easy to check in to version control."
+    "`notebook` or `lab` server wins, making it easy to check in to version control."
    ]
   },
   {
@@ -210,13 +210,11 @@
   },
   {
    "cell_type": "markdown",
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "source": [
-    "### Example: Scala Language Server (metals) integration with jupyterlab-lsp\n",
+    "### Example: Scala Language Server (metals) integration\n",
     "\n",
-    "Step 1: Get a Scala-based kernel installed.\n",
+    "**Step 1:** Get a Scala-based kernel installed.\n",
     "\n",
     "2 possible options: Almond kernel or the Spark magic kernel.\n",
     "\n",
@@ -241,7 +239,7 @@
     "jupyter-kernelspec install sparkmagic/kernels/sparkkernel\n",
     "```\n",
     "\n",
-    "Step 2: Install metals server in the working directory:\n",
+    "**Step 2:** Install metals server in the working directory:\n",
     "\n",
     "Metals has a coursier based installation.\n",
     "\n",
@@ -250,10 +248,12 @@
     "./coursier bootstrap org.scalameta:metals_2.12:0.7.0 --force-fetch -o metals -f\n",
     "```\n",
     "\n",
-    "(Might need to use the --force-fetch flag if you are getting dependency issues.)\n",
+    "(Might need to use the `--force-fetch` flag if you are getting dependency\n",
+    "issues.)\n",
     "\n",
-    "Step 3: Configure the metals server in jupyterlab-lsp. Enter the following in\n",
-    "the jupyter_server_config.json:\n",
+    "**Step 3:** Configure the metals server in jupyterlab-lsp. Enter the following\n",
+    "in the `jupyter/jupyter_server_config.d/metals-ls.json` (in one of the jupyter\n",
+    "configuration directories):\n",
     "\n",
     "```python\n",
     "{\n",
@@ -271,8 +271,8 @@
     "```\n",
     "\n",
     "You are good to go now! Just start `jupyter lab` and create a notebook with\n",
-    "either the Spark or the Scala kernel and you should be able to see the metals\n",
-    "server initialised from the bottom left corner."
+    "either the Spark or the Scala kernel and the metals server should automatically\n",
+    "initialise (the status indicator should show \"Fully initialized\")."
    ]
   }
  ],

docs/Language Servers.ipynb

@@ -6,22 +6,28 @@
    "source": [
     "## Language Servers\n",
     "\n",
-    "`jupyter-lsp` does not come with any Language Servers! However, we will try to\n",
-    "use them if they _are_ installed and we know about them. For the language\n",
-    "servers in the tables below, use one of the suggested package managers to\n",
-    "install them: these implementations are tested to work with `jupyter-lsp`.\n",
+    "By default `jupyter-lsp` does not come with any language servers preinstalled.\n",
+    "However, we will try to use them if they _are_ installed and we know about them\n",
+    "(i.e. someone contributed a full specification).\n",
     "\n",
-    "- _You can disable this feature by configuring_\n",
-    "  [autodetect](./Configuring.ipynb#autodetect)\n",
+    "> _You can disable auto-detection by configuring\n",
+    "> [autodetect](./Configuring.ipynb#autodetect)_\n",
     "\n",
-    "If you do not see a language you would like, but can find it one of these lists:\n",
+    "You can add another language server for languages that are not listed on this\n",
+    "page:\n",
     "\n",
-    "- the [official list][lsp-implementations] of language servers\n",
-    "- a [community-curated list][langserver] of language servers\n",
+    "- using a minimal JSON-based\n",
+    "  [configuration file](./Configuring.ipynb#language_servers) (good for\n",
+    "  experimenting or configuring a niche server), or\n",
+    "- contributing a [full specification](./Contributing.ipynb#Specs) (to enable\n",
+    "  better integration and help other users of the same language)\n",
     "\n",
-    "...you might be able to add it\n",
-    "[via configuration](./Configuring.ipynb#language_servers) or\n",
-    "[build your own spec](./Contributing.ipynb#Specs) for the server in question.\n",
+    "The existing language servers are listed on the [official implementations\n",
+    "list][lsp-implementations] and on the [community-curated list][langserver].\n",
+    "\n",
+    "For the language servers in the tables below, use one of the suggested package\n",
+    "managers to install them: these implementations are tested to work with\n",
+    "`jupyter-lsp`.\n",
     "\n",
     "[language-server]:\n",
     "  https://microsoft.github.io/language-server-protocol/specification\n",
@@ -141,6 +147,15 @@
     ")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The Scala language server (`metals`) is not currently auto-detected, but can be\n",
+    "configured as demonstrated in the\n",
+    "[configuration example](<./Configuring.ipynb#Example:-Scala-Language-Server-(metals)-integration>)."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},