Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Prepare for final release of 5.0 #993

Merged
merged 9 commits into from
Oct 6, 2023
Merged

Prepare for final release of 5.0 #993

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
8863225
Bump version to 5.0.0
krassowski Oct 5, 2023
ae81960
Update extending documentation
krassowski Oct 5, 2023
644f03e
Update releasing
krassowski Oct 5, 2023
d4406f4
Remove docker mention as it does not work two releases back
krassowski Oct 5, 2023
a81b823
Multiple jump targets are now supported
krassowski Oct 5, 2023
72a198d
Update branch name, collapse proposals to a list
krassowski Oct 5, 2023
185233a
Update branch name in CONTRIBUTING, adjust logging and headers
krassowski Oct 5, 2023
ceafef5
Update changelog
krassowski Oct 5, 2023
27177c5
Outdated docker instructions are no more (PRs welcome)
krassowski Oct 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,19 @@
## Changelog

### `@jupyter-lsp/jupyterlab-lsp 5.0.0`

- enhancements:
- uses toast notifications instead of messages on status bar
- diagnostics panel will be re-opened on reload
- maintenance:
- support JupyterLab 4
- use upstream `@jupyterlab/lsp` package
- use camelCase convention in TypeScript/JavaScript code
- use `@codemirror/linter` to show diagnostics
- this comes with a different style of underlines and custom tooltips

Requires JupyterLab `>=4.0.6,<5.0.0a0`

### `@jupyter-lsp/jupyterlab-lsp 5.0.0-rc.1`

- restore re-use of unused standalone connections
Expand Down
33 changes: 20 additions & 13 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@ You can contribute to the project through:

Thank you for all your contributions :heart:

[license]: https://github.com/jupyter-lsp/jupyterlab-lsp/blob/master/LICENSE
[license]: https://github.com/jupyter-lsp/jupyterlab-lsp/blob/main/LICENSE
[extending]: ./docs/Extending.html
[roadmap]: ./docs/Roadmap.html
[jupyterlab-lsp]: https://github.com/jupyter-lsp/jupyterlab-lsp.git
[code-of-conduct]: https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md
[code-of-conduct]: https://github.com/jupyter/governance/blob/main/conduct/code_of_conduct.md

### Set up the environment

Expand All @@ -52,7 +52,7 @@ pip install -r requirements/dev.txt # in a virtualenv, probably
sudo apt-get install nodejs # ... e.g. on debian/ubuntu
```

#### The Easy Way
#### Single-step installation

Once your environment is created and activated, on Linux/OSX you can run:

Expand All @@ -62,7 +62,10 @@ bash binder/postBuild

This performs all the basic setup steps, and is used for the binder demo.

#### The Hard Way
This approach may not always work. Continue reading for a step-by-step
instructions which also show all the underlying pieces.

#### Manual installation

Install `jupyter-lsp` from source in your virtual environment:

Expand Down Expand Up @@ -378,25 +381,25 @@ The spec should only be advertised if the command _could actually_ be run:

otherwise an empty dictionary (`{}`) should be returned.

[built-in specs]: https://github.com/jupyter-lsp/jupyterlab-lsp/tree/master/python_packages/jupyter_lsp/jupyter_lsp/specs
[setup.cfg]: https://github.com/jupyter-lsp/jupyterlab-lsp/blob/master/python_packages/jupyter_lsp/setup.cfg
[schema]: https://github.com/jupyter-lsp/jupyterlab-lsp/blob/master/python_packages/jupyter_lsp/jupyter_lsp/schema/schema.json
[utilities]: https://github.com/jupyter-lsp/jupyterlab-lsp/blob/master/python_packages/jupyter_lsp/jupyter_lsp/specs/utils.py
[built-in specs]: https://github.com/jupyter-lsp/jupyterlab-lsp/tree/main/python_packages/jupyter_lsp/jupyter_lsp/specs
[setup.cfg]: https://github.com/jupyter-lsp/jupyterlab-lsp/blob/main/python_packages/jupyter_lsp/setup.cfg
[schema]: https://github.com/jupyter-lsp/jupyterlab-lsp/blob/main/python_packages/jupyter_lsp/jupyter_lsp/schema/schema.json
[utilities]: https://github.com/jupyter-lsp/jupyterlab-lsp/blob/main/python_packages/jupyter_lsp/jupyter_lsp/specs/utils.py

##### Common Concerns

- some language servers need to have their connection mode specified
- the `stdio` interface is the only one supported by `jupyter_lsp`
- PRs welcome to support other modes!
- because of its VSCode heritage, many language servers use `nodejs`
- many language servers use `nodejs`
- `LanguageServerManager.nodejs` will provide the location of our best
guess at where a user's `nodejs` might be found
- some language servers are hard to start purely from the command line
- use a helper script to encapsulate some complexity, or
- use a command argument of the interpreter is available (see the [r spec][] and [julia spec] for examples)
- use a `command` argument of the interpreter is available (see the [r spec][] and [julia spec] for examples)

[r spec]: https://github.com/jupyter-lsp/jupyterlab-lsp/blob/master/python_packages/jupyter_lsp/jupyter_lsp/specs/r_languageserver.py
[julia spec]: https://github.com/jupyter-lsp/jupyterlab-lsp/blob/master/python_packages/jupyter_lsp/jupyter_lsp/specs/julia_language_server.py
[r spec]: https://github.com/jupyter-lsp/jupyterlab-lsp/blob/main/python_packages/jupyter_lsp/jupyter_lsp/specs/r_languageserver.py
[julia spec]: https://github.com/jupyter-lsp/jupyterlab-lsp/blob/main/python_packages/jupyter_lsp/jupyter_lsp/specs/julia_language_server.py

##### Example: making a pip-installable `cool-language-server` spec

Expand Down Expand Up @@ -462,7 +465,11 @@ python setup.py sdist bdist_wheel

## Debugging

Adjust `loggingLevel` in the `Advanced Settings Editor` -> `Language Server` to see more log messages.
To see more see more log messages navigate to `Settings` ❯ `Settings Editor` ❯ `Language Servers` and adjust:

- adjust `Logging console verbosity level`
- switch `Ask servers to send trace notifications` to `verbose`
- toggle `Log all LSP communication with the LSP servers`

For robot tests set:

Expand Down
60 changes: 10 additions & 50 deletions docs/Architecture.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@
"source": [
"### As-Is\n",
"\n",
"These are how we _think_ everything works in the current `master` branch."
"These are how we _think_ everything works in the current `main` branch."
]
},
{
Expand Down Expand Up @@ -103,54 +103,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Reorganize client source with lerna and typescript projects [#76][]\n",
"\n",
"> TBD\n",
"\n",
"[#76]: https://github.com/jupyter-lsp/jupyterlab-lsp/issues/76"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Add DiagnosticsManager, refactor DiagnosticPanel [#176][]\n",
"\n",
"> TBD\n",
"\n",
"[#176]: https://github.com/jupyter-lsp/jupyterlab-lsp/issues/176"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Multiple sources of LSP messages on frontend and backend [#184][]\n",
"\n",
"> TBD\n",
"\n",
"[#184]: https://github.com/jupyter-lsp/jupyterlab-lsp/issues/184"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Use mime types from server spec for language detection [#190][]\n",
"\n",
"> TBD\n",
"\n",
"[#190]: https://github.com/jupyter-lsp/jupyterlab-lsp/issues/190"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Formalize and extend language transclusion [#191][]\n",
"\n",
"> TBD\n",
"\n",
"- Reorganize client source with lerna and typescript projects [#76][]\n",
"- Add DiagnosticsManager, refactor DiagnosticPanel [#176][]\n",
"- Multiple sources of LSP messages on frontend and backend [#184][]\n",
"- Formalize and extend language transclusion [#191][]\n",
"\n",
"[#76]: https://github.com/jupyter-lsp/jupyterlab-lsp/issues/76\n",
"[#176]: https://github.com/jupyter-lsp/jupyterlab-lsp/issues/176\n",
"[#184]: https://github.com/jupyter-lsp/jupyterlab-lsp/issues/184\n",
"[#191]: https://github.com/jupyter-lsp/jupyterlab-lsp/issues/191"
]
}
Expand All @@ -171,7 +131,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.7.9"
"version": "3.11.4"
},
"widgets": {
"application/vnd.jupyter.widget-state+json": {
Expand Down
121 changes: 42 additions & 79 deletions docs/Extending.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,100 +11,43 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"> Note: the API is likely to change in the future; your suggestions are welcome!\n",
"\n",
"### How to add a new LSP feature?\n",
"\n",
"Features (as well as other parts of the frontend) reuse the\n",
"[JupyterLab plugins system](https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html#plugins).\n",
"Each plugin is a [TypeScript](https://www.typescriptlang.org/) package exporting\n",
"one or more `JupyterFrontEndPlugin`s (see\n",
"[the JupyterLab extesion developer tutorial](https://jupyterlab.readthedocs.io/en/stable/extension/extension_tutorial.html)\n",
"for an overview). Each feature has to register itself with the `FeatureManager`\n",
"(which is provided after requesting `ILSPFeatureManager` token) using\n",
"for an overview).\n",
"\n",
"Each feature has to register itself with the `FeatureManager`\n",
"(which is provided after requesting `ILSPFeatureManager` token from `@jupyterlab/lsp`) using\n",
"`register(options: IFeatureOptions)` method.\n",
"\n",
"Your feature specification should follow the `IFeature` interface, which can be\n",
"divided into three major parts:\n",
"The feature specification should follow the `IFeature` interface as of JupyterLab 4.0, including:\n",
"\n",
"- `editorIntegrationFactory`: constructors for the feature-CodeEditor\n",
" integrators (implementing the `IFeatureEditorIntegration` interface), one for\n",
" each supported CodeEditor (e.g. CodeMirror or Monaco); for CodeMirror\n",
" integration you can base your feature integration on the abstract\n",
" `CodeMirrorIntegration` class.\n",
"- `labIntegration`: an optional object integrating feature with the JupyterLab\n",
" interface\n",
"- `id`: unique identifier of the feature, we recommend `@organization/project:feature` pattern\n",
"- `capabilities`: an optional object defining the [client\n",
" capabilities][clientcapabilities] implemented by your feature,\n",
"- optional fields for easy integration of some of the common JupyterLab systems,\n",
" such as:\n",
" - settings system\n",
" - commands system (including context menu)\n",
"\n",
"For further integration with the JupyterLab, you can request additional\n",
"JupyterLab tokens (consult JupyterLab documentation on\n",
"[core tokens](https://jupyterlab.readthedocs.io/en/stable/extension/extension_points.html#core-tokens)).\n",
"See JupyterLab [Extension Points >> LSP Features](https://jupyterlab.readthedocs.io/en/latest/extension/extension_points.html#lsp-features) documentation for more details.\n",
"\n",
"#### How to override the default implementation of a feature?\n",
"\n",
"You can specify a list of extensions to be disabled the the feature manager\n",
"passing their plugin identifiers in `supersedes` field of `IFeatureOptions`.\n",
"You can specify a list of plugins implementing features which you want to\n",
"disable in [`jupyterlab.disabledExtensions`][disabledExtensions] stanza of `package.json`, for example:\n",
"\n",
"```json\n",
"\"jupyterlab\": {\n",
" \"disabledExtensions\": [\"@jupyter-lsp/jupyterlab-lsp:hover\"]\n",
"}\n",
"```\n",
"\n",
"will disable the hover feature.\n",
"\n",
"[clientCapabilities]:\n",
"https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#clientCapabilities]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### How to integrate a new code editor implementation?\n",
"\n",
"`CodeMirrorEditor` code editor is supported by default, but any JupyterLab\n",
"editor implementing the `CodeEditor.IEditor` interface can be adapted for the\n",
"use with the LSP extension. To add your custom code editor (e.g. Monaco) after\n",
"implementing a `CodeEditor.IEditor` interface wrapper (which you would have\n",
"anyways for the JupyterLab integration), you need to also implement a virtual\n",
"editor (`IVirtualEditor` interface) for it.\n",
"\n",
"#### Why virtual editor?\n",
"\n",
"The virtual editor takes multiple instances of your editor (e.g. in a notebook)\n",
"and makes them act like a single editor. For example, when \"onKeyPress\" event is\n",
"bound on the VirtualEditor instance, it should be bound onto each actual code\n",
"editor; this allows the features to be implemented without the knowledge about\n",
"the number of editor instances on the page.\n",
"\n",
"#### How to register the implementation?\n",
"\n",
"A `virtualEditorManager` will be provided if you request\n",
"`ILSPVirtualEditorManager` token; use\n",
"`registerEditorType(options: IVirtualEditorType<IEditor>)` method passing a name\n",
"that you will also use to identify the code editor, the editor class, and your\n",
"VirtualEditor constructor."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### How to integrate a new `DocumentWidget`?\n",
"\n",
"JupyterLab editor widgets (such as _Notebook_ or _File Editor_) implement\n",
"`IDocumentWidget` interface. Each such widget has to adapted by a\n",
"`WidgetAdapter` to enable its use with the LSP extension. The role of the\n",
"`WidgetAdapter` is to extract the document metadata (language, mimetype) and the\n",
"underlying code editor (e.g. CodeMirror or Monaco) instances so that other parts\n",
"of the LSP extension can interface with them without knowing about the\n",
"implementation details of the DocumentWidget (or even about the existence of a\n",
"Notebook construct!).\n",
"\n",
"Your custom `WidgetAdapter` implementation has to register itself with\n",
"`WidgetAdapterManager` (which can be requested with `ILSPAdapterManager` token),\n",
"calling `registerAdapterType(options: IAdapterTypeOptions)` method. Among the\n",
"options, in addition to the custom `WidgetAdapter`, you need to provide a\n",
"tracker (`IWidgetTracker`) which will notify the extension via a signal when a\n",
"new instance of your document widget is getting created."
"https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#clientCapabilities]\n",
"[disabledExtensions]: https://jupyterlab.readthedocs.io/en/latest/extension/extension_dev.html#disabling-other-extensions"
]
},
{
Expand All @@ -120,8 +63,8 @@
"\n",
"#### Future plans for transclusions handling\n",
"\n",
"We will strive to make it possible for kernels to register their custom\n",
"syntax/code transformations easily, but the frontend API will remain available\n",
"We welcome pull requests enabling kernels to register their custom\n",
"syntax/code transformations. The frontend API will remain available\n",
"for the end-users who write their custom syntax modifications with actionable\n",
"side-effects (e.g. a custom IPython magic which copies a variable from the host\n",
"document to the embedded document)."
Expand Down Expand Up @@ -166,6 +109,26 @@
"[theme-vscode](https://github.com/jupyter-lsp/jupyterlab-lsp/tree/master/packages/theme-vscode)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Migrating to v5.0"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"- `IFeature` interface was moved to `@jupyterlab/lsp`\n",
" - `labIntegration` was removed,\n",
" - `editorIntegrationFactory` was removed in JupyterLab 4.0 and restored in JupyterLab 4.1 as `extensionFactory` with new API (`ILSPEditorExtensionFactory`),\n",
" - `supersedes` was removed; you can disable extensions using the JupyterLab native `jupyterlab.disabledExtensions` stanza of `package.json`.\n",
"- `ILSPCompletionThemeManager`:\n",
" - `register_theme()` was renamed to `registerTheme()`\n",
" - all other methods were renamed to follow camelCase convention\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
Expand Down Expand Up @@ -306,7 +269,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.7.9"
"version": "3.11.4"
},
"widgets": {
"application/vnd.jupyter.widget-state+json": {
Expand Down
Loading