{ "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": [ "#### virtual_documents_dir\n", "\n", "> default: os.getenv(\"JP_LSP_VIRTUAL_DIR\", \".virtual_documents\")\n", "\n", "Path to virtual documents relative to the content manager root directory.\n", "\n", "Its default value can be set with `JP_LSP_VIRTUAL_DIR` environment variable and\n", "fallback to `.virtual_documents`." ] }, { "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." ] } ], "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 }