Configuring backend¶
Configuration Files¶
Like the Jupyter Notebook server, JupyterHub, and other Jupyter interactive computing tools, jupyter-lsp
can be configured via Python or JSON files in well-known locations. You can find out where to put them on your system with:
jupyter --paths
They will be merged from bottom to top, and the directory where you launch your notebook
server wins, making it easy to check in to version control.
Configuration Options¶
language_servers¶
jupyter-lsp
does not come with any Language Servers! However, we will try to use known language servers if they are installed and we know about them: you can disable this behavior by configuring autodetect.
If you don’t see an implementation for the language server you need, continue reading!
Please consider contributing your language server spec to
jupyter-lsp
!
The absolute minimum language server spec requires:
argv
, a list of shell tokens to launch the server instdio
mode (as opposed totcp
),shell tokens are arrays of strings representing command line commands with arguments, for example
ls -l
is represented as["ls", "-l"]
whilemkdir "new directory"
should be split into["mkdir", "new directory"]
; If you have Python installed, you can useshlex.split("your command")
to get such an array.the
languages
which the server will respond to, andthe schema
version
of the spec (currently2
)
# ./jupyter_server_config.json ---------- unique! -----------
# | |
# or e.g. V V
# $PREFIX/etc/jupyter/jupyter_server_config.d/a-language-server-implementation.json
{
"LanguageServerManager": {
"language_servers": {
"a-language-server-implementation": {
"version": 2,
"argv": ["/absolute/path/to/a-language-server", "--stdio"],
"languages": ["a-language"]
}
}
}
}
A number of other options we hope to use to enrich the user experience are available in the schema.
More complex configurations that can’t be hard-coded may benefit from the python approach:
# jupyter_server_config.py
import shutil
# c is a magic, lazy variable
c.LanguageServerManager.language_servers = {
"a-language-server-implementation": {
# if installed as a binary
"argv": [shutil.which("a-language-server")],
"languages": ["a-language"],
"version": 2
},
"another-language-implementation": {
# if run like a script
"argv": [shutil.which("another-language-interpreter"), "another-language-server"],
"languages": ["another-language"],
"version": 2
}
}
nodejs¶
default:
None
An absolute path to your nodejs
executable. If None
, nodejs
will be detected in a number of well-known places.
autodetect¶
default:
True
If True
, jupyter-lsp
will look for all known language servers. User-configured language_servers
of the same implementation will be preferred over autodetect
ed ones.
node_roots¶
default:
[]
Absolute paths to search for directories named node_modules
, such as nodejs
-backed language servers. The order is, roughly:
the folder where
notebook
orlab
was launchedthe JupyterLab
staging
folderwherever
conda
puts global node moduleswherever some other conventions put it
extra_node_roots¶
default:
[]
Additional places jupyter-lsp
will look for node_modules
. These will be checked before node_roots
, and should not contain the trailing node_modules
.
virtual_documents_dir¶
default: os.getenv(“JP_LSP_VIRTUAL_DIR”, “.virtual_documents”)
Path to virtual documents relative to the content manager root directory.
Its default value can be set with JP_LSP_VIRTUAL_DIR
environment variable and fallback to .virtual_documents
.
Python entry_points
¶
pip
-installable packages in the same environment as the Jupyter notebook
server can be automatically detected as providing language_servers. These are a little more involved, but also more powerful: see more in Contributing. Servers configured this way are loaded before those defined in configuration files, so that a user can fine-tune their available servers.
Example: Scala Language Server (metals) integration with jupyterlab-lsp¶
Step 1: Get a Scala-based kernel installed.
2 possible options: Almond kernel or the Spark magic kernel.
Almond kernel install:
$ curl -Lo coursier https://git.io/coursier-cli
$ chmod +x coursier
$ ./coursier launch --fork almond -- --install
$ rm -f coursier
Spark Magic kernel:
pip install sparkmagic
Now, install the spark kernel:
jupyter-kernelspec install sparkmagic/kernels/sparkkernel
Step 2: Install metals server in the working directory:
Metals has a coursier based installation.
curl -Lo coursier https://git.io/coursier-cli && chmod +x coursier
./coursier bootstrap org.scalameta:metals_2.12:0.7.0 --force-fetch -o metals -f
(Might need to use the –force-fetch flag if you are getting dependency issues.)
Step 3: Configure the metals server in jupyterlab-lsp. Enter the following in the jupyter_server_config.json:
{
"LanguageServerManager": {
"language_servers": {
"metals": {
"version": 2,
"argv": ["<$path_to_metals_server(eg:/Users/skakker/projects/jupyterlab-lsp/metals)>"],
"languages": ["scala"],
"mime_types": ["text/x-scala"]
}
}
}
}
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.