|
11 | 11 | "cell_type": "markdown", |
12 | 12 | "metadata": {}, |
13 | 13 | "source": [ |
14 | | - "> Note: the API is likely to change in the future; your suggestions are welcome!\n", |
15 | | - "\n", |
16 | 14 | "### How to add a new LSP feature?\n", |
17 | 15 | "\n", |
18 | 16 | "Features (as well as other parts of the frontend) reuse the\n", |
19 | 17 | "[JupyterLab plugins system](https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html#plugins).\n", |
20 | 18 | "Each plugin is a [TypeScript](https://www.typescriptlang.org/) package exporting\n", |
21 | 19 | "one or more `JupyterFrontEndPlugin`s (see\n", |
22 | 20 | "[the JupyterLab extesion developer tutorial](https://jupyterlab.readthedocs.io/en/stable/extension/extension_tutorial.html)\n", |
23 | | - "for an overview). Each feature has to register itself with the `FeatureManager`\n", |
24 | | - "(which is provided after requesting `ILSPFeatureManager` token) using\n", |
| 21 | + "for an overview).\n", |
| 22 | + "\n", |
| 23 | + "Each feature has to register itself with the `FeatureManager`\n", |
| 24 | + "(which is provided after requesting `ILSPFeatureManager` token from `@jupyterlab/lsp`) using\n", |
25 | 25 | "`register(options: IFeatureOptions)` method.\n", |
26 | 26 | "\n", |
27 | | - "Your feature specification should follow the `IFeature` interface, which can be\n", |
28 | | - "divided into three major parts:\n", |
| 27 | + "The feature specification should follow the `IFeature` interface as of JupyterLab 4.0, including:\n", |
29 | 28 | "\n", |
30 | | - "- `editorIntegrationFactory`: constructors for the feature-CodeEditor\n", |
31 | | - " integrators (implementing the `IFeatureEditorIntegration` interface), one for\n", |
32 | | - " each supported CodeEditor (e.g. CodeMirror or Monaco); for CodeMirror\n", |
33 | | - " integration you can base your feature integration on the abstract\n", |
34 | | - " `CodeMirrorIntegration` class.\n", |
35 | | - "- `labIntegration`: an optional object integrating feature with the JupyterLab\n", |
36 | | - " interface\n", |
| 29 | + "- `id`: unique identifier of the feature, we recommend `@organization/project:feature` pattern\n", |
37 | 30 | "- `capabilities`: an optional object defining the [client\n", |
38 | 31 | " capabilities][clientcapabilities] implemented by your feature,\n", |
39 | | - "- optional fields for easy integration of some of the common JupyterLab systems,\n", |
40 | | - " such as:\n", |
41 | | - " - settings system\n", |
42 | | - " - commands system (including context menu)\n", |
43 | 32 | "\n", |
44 | | - "For further integration with the JupyterLab, you can request additional\n", |
45 | | - "JupyterLab tokens (consult JupyterLab documentation on\n", |
46 | | - "[core tokens](https://jupyterlab.readthedocs.io/en/stable/extension/extension_points.html#core-tokens)).\n", |
| 33 | + "See JupyterLab [Extension Points >> LSP Features](https://jupyterlab.readthedocs.io/en/latest/extension/extension_points.html#lsp-features) documentation for more details.\n", |
47 | 34 | "\n", |
48 | 35 | "#### How to override the default implementation of a feature?\n", |
49 | 36 | "\n", |
50 | | - "You can specify a list of extensions to be disabled the the feature manager\n", |
51 | | - "passing their plugin identifiers in `supersedes` field of `IFeatureOptions`.\n", |
| 37 | + "You can specify a list of plugins implementing features which you want to\n", |
| 38 | + "disable in [`jupyterlab.disabledExtensions`][disabledExtensions] stanza of `package.json`, for example:\n", |
| 39 | + "\n", |
| 40 | + "```json\n", |
| 41 | + "\"jupyterlab\": {\n", |
| 42 | + " \"disabledExtensions\": [\"@jupyter-lsp/jupyterlab-lsp:hover\"]\n", |
| 43 | + "}\n", |
| 44 | + "```\n", |
| 45 | + "\n", |
| 46 | + "will disable the hover feature.\n", |
52 | 47 | "\n", |
53 | 48 | "[clientCapabilities]:\n", |
54 | | - "https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#clientCapabilities]" |
55 | | - ] |
56 | | - }, |
57 | | - { |
58 | | - "cell_type": "markdown", |
59 | | - "metadata": {}, |
60 | | - "source": [ |
61 | | - "### How to integrate a new code editor implementation?\n", |
62 | | - "\n", |
63 | | - "`CodeMirrorEditor` code editor is supported by default, but any JupyterLab\n", |
64 | | - "editor implementing the `CodeEditor.IEditor` interface can be adapted for the\n", |
65 | | - "use with the LSP extension. To add your custom code editor (e.g. Monaco) after\n", |
66 | | - "implementing a `CodeEditor.IEditor` interface wrapper (which you would have\n", |
67 | | - "anyways for the JupyterLab integration), you need to also implement a virtual\n", |
68 | | - "editor (`IVirtualEditor` interface) for it.\n", |
69 | | - "\n", |
70 | | - "#### Why virtual editor?\n", |
71 | | - "\n", |
72 | | - "The virtual editor takes multiple instances of your editor (e.g. in a notebook)\n", |
73 | | - "and makes them act like a single editor. For example, when \"onKeyPress\" event is\n", |
74 | | - "bound on the VirtualEditor instance, it should be bound onto each actual code\n", |
75 | | - "editor; this allows the features to be implemented without the knowledge about\n", |
76 | | - "the number of editor instances on the page.\n", |
77 | | - "\n", |
78 | | - "#### How to register the implementation?\n", |
79 | | - "\n", |
80 | | - "A `virtualEditorManager` will be provided if you request\n", |
81 | | - "`ILSPVirtualEditorManager` token; use\n", |
82 | | - "`registerEditorType(options: IVirtualEditorType<IEditor>)` method passing a name\n", |
83 | | - "that you will also use to identify the code editor, the editor class, and your\n", |
84 | | - "VirtualEditor constructor." |
85 | | - ] |
86 | | - }, |
87 | | - { |
88 | | - "cell_type": "markdown", |
89 | | - "metadata": {}, |
90 | | - "source": [ |
91 | | - "### How to integrate a new `DocumentWidget`?\n", |
92 | | - "\n", |
93 | | - "JupyterLab editor widgets (such as _Notebook_ or _File Editor_) implement\n", |
94 | | - "`IDocumentWidget` interface. Each such widget has to adapted by a\n", |
95 | | - "`WidgetAdapter` to enable its use with the LSP extension. The role of the\n", |
96 | | - "`WidgetAdapter` is to extract the document metadata (language, mimetype) and the\n", |
97 | | - "underlying code editor (e.g. CodeMirror or Monaco) instances so that other parts\n", |
98 | | - "of the LSP extension can interface with them without knowing about the\n", |
99 | | - "implementation details of the DocumentWidget (or even about the existence of a\n", |
100 | | - "Notebook construct!).\n", |
101 | | - "\n", |
102 | | - "Your custom `WidgetAdapter` implementation has to register itself with\n", |
103 | | - "`WidgetAdapterManager` (which can be requested with `ILSPAdapterManager` token),\n", |
104 | | - "calling `registerAdapterType(options: IAdapterTypeOptions)` method. Among the\n", |
105 | | - "options, in addition to the custom `WidgetAdapter`, you need to provide a\n", |
106 | | - "tracker (`IWidgetTracker`) which will notify the extension via a signal when a\n", |
107 | | - "new instance of your document widget is getting created." |
| 49 | + "https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#clientCapabilities]\n", |
| 50 | + "[disabledExtensions]: https://jupyterlab.readthedocs.io/en/latest/extension/extension_dev.html#disabling-other-extensions" |
108 | 51 | ] |
109 | 52 | }, |
110 | 53 | { |
|
120 | 63 | "\n", |
121 | 64 | "#### Future plans for transclusions handling\n", |
122 | 65 | "\n", |
123 | | - "We will strive to make it possible for kernels to register their custom\n", |
124 | | - "syntax/code transformations easily, but the frontend API will remain available\n", |
| 66 | + "We welcome pull requests enabling kernels to register their custom\n", |
| 67 | + "syntax/code transformations. The frontend API will remain available\n", |
125 | 68 | "for the end-users who write their custom syntax modifications with actionable\n", |
126 | 69 | "side-effects (e.g. a custom IPython magic which copies a variable from the host\n", |
127 | 70 | "document to the embedded document)." |
|
166 | 109 | "[theme-vscode](https://github.com/jupyter-lsp/jupyterlab-lsp/tree/master/packages/theme-vscode)." |
167 | 110 | ] |
168 | 111 | }, |
| 112 | + { |
| 113 | + "cell_type": "markdown", |
| 114 | + "metadata": {}, |
| 115 | + "source": [ |
| 116 | + "### Migrating to v5.0" |
| 117 | + ] |
| 118 | + }, |
| 119 | + { |
| 120 | + "cell_type": "markdown", |
| 121 | + "metadata": {}, |
| 122 | + "source": [ |
| 123 | + "- `IFeature` interface was moved to `@jupyterlab/lsp`\n", |
| 124 | + " - `labIntegration` was removed,\n", |
| 125 | + " - `editorIntegrationFactory` was removed in JupyterLab 4.0 and restored in JupyterLab 4.1 as `extensionFactory` with new API (`ILSPEditorExtensionFactory`),\n", |
| 126 | + " - `supersedes` was removed; you can disable extensions using the JupyterLab native `jupyterlab.disabledExtensions` stanza of `package.json`.\n", |
| 127 | + "- `ILSPCompletionThemeManager`:\n", |
| 128 | + " - `register_theme()` was renamed to `registerTheme()`\n", |
| 129 | + " - all other methods were renamed to follow camelCase convention\n" |
| 130 | + ] |
| 131 | + }, |
169 | 132 | { |
170 | 133 | "cell_type": "markdown", |
171 | 134 | "metadata": {}, |
|
306 | 269 | "name": "python", |
307 | 270 | "nbconvert_exporter": "python", |
308 | 271 | "pygments_lexer": "ipython3", |
309 | | - "version": "3.7.9" |
| 272 | + "version": "3.11.4" |
310 | 273 | }, |
311 | 274 | "widgets": { |
312 | 275 | "application/vnd.jupyter.widget-state+json": { |
|
0 commit comments