|
| 1 | +{ |
| 2 | + "cells": [ |
| 3 | + { |
| 4 | + "cell_type": "markdown", |
| 5 | + "metadata": {}, |
| 6 | + "source": [ |
| 7 | + "## Configuring" |
| 8 | + ] |
| 9 | + }, |
| 10 | + { |
| 11 | + "cell_type": "markdown", |
| 12 | + "metadata": {}, |
| 13 | + "source": [ |
| 14 | + "### Configuration Files\n", |
| 15 | + "\n", |
| 16 | + "Like the Jupyter Notebook server, JupyterHub, and other Jupyter interactive computing\n", |
| 17 | + "tools, `jupyter-lsp` can be configured via [Python or JSON files][notebook-config]\n", |
| 18 | + "in _well-known locations_. You can find out where to put them on your system with:\n", |
| 19 | + "\n", |
| 20 | + "[notebook-config]: https://jupyter-notebook.readthedocs.io/en/stable/config.html\n", |
| 21 | + "\n", |
| 22 | + "```bash\n", |
| 23 | + "jupyter --paths\n", |
| 24 | + "```\n", |
| 25 | + "\n", |
| 26 | + "They will be merged from bottom to top, and the directory where you launch your\n", |
| 27 | + "`notebook` server wins, making it easy to check in to version control. " |
| 28 | + ] |
| 29 | + }, |
| 30 | + { |
| 31 | + "cell_type": "markdown", |
| 32 | + "metadata": {}, |
| 33 | + "source": [ |
| 34 | + "### Configuration Options" |
| 35 | + ] |
| 36 | + }, |
| 37 | + { |
| 38 | + "cell_type": "markdown", |
| 39 | + "metadata": {}, |
| 40 | + "source": [ |
| 41 | + "#### language_servers\n", |
| 42 | + "\n", |
| 43 | + "`jupyter-lsp` does not come with any Language Servers! However, we will try to use\n", |
| 44 | + "[known language servers](./Language%20Servers.ipynb) if they _are_ installed and we know about them: you can disable this behavior\n", |
| 45 | + "by configuring [autodetect](#autodetect). \n", |
| 46 | + "\n", |
| 47 | + "If you don't see an implementation for the language server you need, continue\n", |
| 48 | + "reading!\n", |
| 49 | + "\n", |
| 50 | + "> Please consider [contributing your language server spec](../Contributing.md)\n", |
| 51 | + "> to `jupyter-lsp`!" |
| 52 | + ] |
| 53 | + }, |
| 54 | + { |
| 55 | + "cell_type": "markdown", |
| 56 | + "metadata": {}, |
| 57 | + "source": [ |
| 58 | + "The absolute minimum language server spec requires:\n", |
| 59 | + "\n", |
| 60 | + "- `argv`, a list of shell tokens to launch the server in `stdio` mode (as opposed to `tcp`),\n", |
| 61 | + "- the `languages` which the server will respond to, and\n", |
| 62 | + "- the schema `version` of the spec (currently only `1`) \n", |
| 63 | + "\n", |
| 64 | + "```python\n", |
| 65 | + "# ./jupyter_notebook_config.json ---------- unique! -----------\n", |
| 66 | + "# | |\n", |
| 67 | + "# or e.g. V V\n", |
| 68 | + "# $PREFIX/etc/jupyter/jupyter_notebook_config.d/a-language-server-implementation.json\n", |
| 69 | + "{\n", |
| 70 | + " \"LanguageServerManager\": {\n", |
| 71 | + " \"language_servers\": {\n", |
| 72 | + " \"a-language-server-implementation\": {\n", |
| 73 | + " \"version\": 1,\n", |
| 74 | + " \"argv\": [\"/absolute/path/to/a-language-server\", \"--stdio\"],\n", |
| 75 | + " \"languages\": [\"a-language\"]\n", |
| 76 | + " }\n", |
| 77 | + " }\n", |
| 78 | + " }\n", |
| 79 | + "}\n", |
| 80 | + "```" |
| 81 | + ] |
| 82 | + }, |
| 83 | + { |
| 84 | + "cell_type": "markdown", |
| 85 | + "metadata": {}, |
| 86 | + "source": [ |
| 87 | + "A number of other options we hope to use to enrich the user experience are available in the\n", |
| 88 | + "[schema][].\n", |
| 89 | + "\n", |
| 90 | + "[schema]: https://github.com/krassowski/jupyterlab-lsp/blob/master/py_src/jupyter_lsp/schema/schema.json\n", |
| 91 | + "\n", |
| 92 | + "More complex configurations that can't be hard-coded may benefit from the python approach:\n", |
| 93 | + "\n", |
| 94 | + "```python\n", |
| 95 | + "# jupyter_notebook_config.py\n", |
| 96 | + "import shutil\n", |
| 97 | + "\n", |
| 98 | + "# c is a magic, lazy variable\n", |
| 99 | + "c.LanguageServerManager.language_servers = {\n", |
| 100 | + " \"a-language-server-implementation\": {\n", |
| 101 | + " # if installed as a binary\n", |
| 102 | + " \"argv\": [shutil.which(\"a-language-server\")],\n", |
| 103 | + " \"languages\": [\"a-language\"]\n", |
| 104 | + " },\n", |
| 105 | + " \"another-language-implementation\": {\n", |
| 106 | + " # if run like a script\n", |
| 107 | + " \"argv\": [shutil.which(\"another-language-interpreter\"), \"another-language-server\"],\n", |
| 108 | + " \"languages\": [\"another-language\"]\n", |
| 109 | + " }\n", |
| 110 | + "}\n", |
| 111 | + "```" |
| 112 | + ] |
| 113 | + }, |
| 114 | + { |
| 115 | + "cell_type": "markdown", |
| 116 | + "metadata": {}, |
| 117 | + "source": [ |
| 118 | + "#### nodejs\n", |
| 119 | + "\n", |
| 120 | + "> default: `None`\n", |
| 121 | + "\n", |
| 122 | + "An absolute path to your `nodejs` executable. If `None`, `nodejs` will be detected in a number of well-known places." |
| 123 | + ] |
| 124 | + }, |
| 125 | + { |
| 126 | + "cell_type": "markdown", |
| 127 | + "metadata": {}, |
| 128 | + "source": [ |
| 129 | + "#### autodetect\n", |
| 130 | + "\n", |
| 131 | + "> default: `True`\n", |
| 132 | + "\n", |
| 133 | + "`jupyter-lsp` will look for all [known language servers](#installing-language-servers).\n", |
| 134 | + "User-configured `language_servers` of the same implementation will be preferred\n", |
| 135 | + "over `autodetect`ed ones." |
| 136 | + ] |
| 137 | + }, |
| 138 | + { |
| 139 | + "cell_type": "markdown", |
| 140 | + "metadata": {}, |
| 141 | + "source": [ |
| 142 | + "#### node_roots\n", |
| 143 | + "\n", |
| 144 | + "> default: `[]`\n", |
| 145 | + "\n", |
| 146 | + "Absolute paths to search for directories named `node_modules`, such as `nodejs`-backed language servers. The order is, roughly:\n", |
| 147 | + "\n", |
| 148 | + "- the folder where `notebook` or `lab` was launched\n", |
| 149 | + "- the JupyterLab `staging` folder\n", |
| 150 | + "- wherever `conda` puts global node modules\n", |
| 151 | + "- wherever some other conventions put it" |
| 152 | + ] |
| 153 | + }, |
| 154 | + { |
| 155 | + "cell_type": "markdown", |
| 156 | + "metadata": {}, |
| 157 | + "source": [ |
| 158 | + "#### extra_node_roots\n", |
| 159 | + "\n", |
| 160 | + "> default: `[]`\n", |
| 161 | + "\n", |
| 162 | + "Additional places `jupyter-lsp` will look for `node_modules`. These will be checked\n", |
| 163 | + "_before_ `node_roots`, and should not contain the trailing `node_modules`." |
| 164 | + ] |
| 165 | + }, |
| 166 | + { |
| 167 | + "cell_type": "markdown", |
| 168 | + "metadata": {}, |
| 169 | + "source": [ |
| 170 | + "### Python `entry_points`\n", |
| 171 | + "\n", |
| 172 | + "`pip`-installable packages in the same environment as the Jupyter `notebook` server\n", |
| 173 | + "can be automatically detected as providing [language_servers](#language_servers). These are a\n", |
| 174 | + "little more involved, but also more powerful: see more in [Configuring](Contributing.md).\n", |
| 175 | + "Servers configured this way are loaded _before_ those defined in \n", |
| 176 | + "[configuration files](#Configuration-Files), so that a user can fine-tune their available\n", |
| 177 | + "servers." |
| 178 | + ] |
| 179 | + } |
| 180 | + ], |
| 181 | + "metadata": { |
| 182 | + "kernelspec": { |
| 183 | + "display_name": "Python 3", |
| 184 | + "language": "python", |
| 185 | + "name": "python3" |
| 186 | + }, |
| 187 | + "language_info": { |
| 188 | + "codemirror_mode": { |
| 189 | + "name": "ipython", |
| 190 | + "version": 3 |
| 191 | + }, |
| 192 | + "file_extension": ".py", |
| 193 | + "mimetype": "text/x-python", |
| 194 | + "name": "python", |
| 195 | + "nbconvert_exporter": "python", |
| 196 | + "pygments_lexer": "ipython3", |
| 197 | + "version": "3.7.6" |
| 198 | + } |
| 199 | + }, |
| 200 | + "nbformat": 4, |
| 201 | + "nbformat_minor": 4 |
| 202 | +} |
0 commit comments