docs/Configuring.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Configuring backend"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Configuration Files\n",
    "\n",
    "Like the Jupyter Notebook server, JupyterHub, and other Jupyter interactive\n",
    "computing tools, `jupyter-lsp` can be configured via [Python or JSON\n",
    "files][notebook-config] in _well-known locations_. You can find out where to put\n",
    "them on your system with:\n",
    "\n",
    "[notebook-config]: https://jupyter-notebook.readthedocs.io/en/stable/config.html\n",
    "\n",
    "```bash\n",
    "jupyter --paths\n",
    "```\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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Configuration Options"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### language_servers\n",
    "\n",
    "`jupyter-lsp` does not come with any Language Servers! However, we will try to\n",
    "use [known language servers](./Language%20Servers.ipynb) if they _are_ installed\n",
    "and we know about them: you can disable this behavior by configuring\n",
    "[autodetect](#autodetect).\n",
    "\n",
    "If you don't see an implementation for the language server you need, continue\n",
    "reading!\n",
    "\n",
    "> Please consider [contributing your language server spec](./Contributing.ipynb)\n",
    "> to `jupyter-lsp`!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The absolute minimum language server spec requires:\n",
    "\n",
    "- `argv`, a list of shell tokens to launch the server in `stdio` mode (as\n",
    "  opposed to `tcp`),\n",
    "- the `languages` which the server will respond to, and\n",
    "- the schema `version` of the spec (currently `2`)\n",
    "\n",
    "```python\n",
    "# ./jupyter_notebook_config.json                 ---------- unique! -----------\n",
    "#                                               |                              |\n",
    "# or e.g.                                       V                              V\n",
    "# $PREFIX/etc/jupyter/jupyter_notebook_config.d/a-language-server-implementation.json\n",
    "{\n",
    "  \"LanguageServerManager\": {\n",
    "    \"language_servers\": {\n",
    "      \"a-language-server-implementation\": {\n",
    "        \"version\": 2,\n",
    "        \"argv\": [\"/absolute/path/to/a-language-server\", \"--stdio\"],\n",
    "        \"languages\": [\"a-language\"]\n",
    "      }\n",
    "    }\n",
    "  }\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A number of other options we hope to use to enrich the user experience are\n",
    "available in the [schema][].\n",
    "\n",
    "[schema]:\n",
    "  https://github.com/krassowski/jupyterlab-lsp/blob/master/py_src/jupyter_lsp/schema/schema.json\n",
    "\n",
    "More complex configurations that can't be hard-coded may benefit from the python\n",
    "approach:\n",
    "\n",
    "```python\n",
    "# jupyter_notebook_config.py\n",
    "import shutil\n",
    "\n",
    "# c is a magic, lazy variable\n",
    "c.LanguageServerManager.language_servers = {\n",
    "    \"a-language-server-implementation\": {\n",
    "        # if installed as a binary\n",
    "        \"argv\": [shutil.which(\"a-language-server\")],\n",
    "        \"languages\": [\"a-language\"],\n",
    "        \"version\": 2\n",
    "    },\n",
    "    \"another-language-implementation\": {\n",
    "        # if run like a script\n",
    "        \"argv\": [shutil.which(\"another-language-interpreter\"), \"another-language-server\"],\n",
    "        \"languages\": [\"another-language\"],\n",
    "        \"version\": 2\n",
    "    }\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### nodejs\n",
    "\n",
    "> default: `None`\n",
    "\n",
    "An absolute path to your `nodejs` executable. If `None`, `nodejs` will be\n",
    "detected in a number of well-known places."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### autodetect\n",
    "\n",
    "> default: `True`\n",
    "\n",
    "If `True`, `jupyter-lsp` will look for all\n",
    "[known language servers](#installing-language-servers). User-configured\n",
    "`language_servers` of the same implementation will be preferred over\n",
    "`autodetect`ed ones."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### node_roots\n",
    "\n",
    "> default: `[]`\n",
    "\n",
    "Absolute paths to search for directories named `node_modules`, such as\n",
    "`nodejs`-backed language servers. The order is, roughly:\n",
    "\n",
    "- the folder where `notebook` or `lab` was launched\n",
    "- the JupyterLab `staging` folder\n",
    "- wherever `conda` puts global node modules\n",
    "- wherever some other conventions put it"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### extra_node_roots\n",
    "\n",
    "> default: `[]`\n",
    "\n",
    "Additional places `jupyter-lsp` will look for `node_modules`. These will be\n",
    "checked _before_ `node_roots`, and should not contain the trailing\n",
    "`node_modules`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python `entry_points`\n",
    "\n",
    "`pip`-installable packages in the same environment as the Jupyter `notebook`\n",
    "server can be automatically detected as providing\n",
    "[language_servers](#language_servers). These are a little more involved, but\n",
    "also more powerful: see more in [Contributing](Contributing.ipynb#Specs).\n",
    "Servers configured this way are loaded _before_ those defined in\n",
    "[configuration files](#Configuration-Files), so that a user can fine-tune their\n",
    "available servers."
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Example: Scala Language Server (metals) integration with jupyterlab-lsp\n",
    "\n",
    "Step 1: Get a Scala-based kernel installed.\n",
    "\n",
    "2 possible options: Almond kernel or the Spark magic kernel.\n",
    "\n",
    "Almond kernel install:\n",
    "\n",
    "```bash\n",
    "$ curl -Lo coursier https://git.io/coursier-cli\n",
    "$ chmod +x coursier\n",
    "$ ./coursier launch --fork almond -- --install\n",
    "$ rm -f coursier\n",
    "```\n",
    "Spark Magic kernel:\n",
    "\n",
    "```bash\n",
    "pip install sparkmagic\n",
    "```\n",
    "Now, install the spark kernel:\n",
    "\n",
    "```bash\n",
    "jupyter-kernelspec install sparkmagic/kernels/sparkkernel\n",
    "```\n",
    "\n",
    "Step 2: Install metals server in the working directory:\n",
    "\n",
    "Metals has a coursier based installation.\n",
    "\n",
    "```bash\n",
    "curl -Lo coursier https://git.io/coursier-cli && chmod +x coursier\n",
    "./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",
    "\n",
    "Step 3: Configure the metals server in jupyterlab-lsp. Enter the following in the jupyter_server_config.json:\n",
    "\n",
    "```python\n",
    "{\n",
    "  \"LanguageServerManager\": {\n",
    "    \"language_servers\": {\n",
    "      \"metals\": {\n",
    "        \"version\": 2,\n",
    "        \"argv\": [\"<$path_to_metals_server(eg:/Users/skakker/projects/jupyterlab-lsp/metals)>\"],\n",
    "        \"languages\": [\"scala\"],\n",
    "        \"mime_types\": [\"text/x-scala\"]\n",
    "      }\n",
    "    }\n",
    "  }\n",
    "}\n",
    "```\n",
    "\n",
    "You are good to go now! Just start `jupyter lab` and create a notebook with either the Spark or the Scala kernel and you should be able to see the metals server initialised from the bottom left corner."
   ],
   "metadata": {
    "collapsed": false
   }
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}