From d33a03cbf14def76deac4435de3aa30b834cfa8d Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Wed, 10 Dec 2025 14:33:06 +0000 Subject: [PATCH] Clarify that notebook cell text sync follows textDocumentSync.change (#2209) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Initial plan * Add textContentSyncKind to NotebookDocumentSyncOptions for cell text sync negotiation Co-authored-by: dbaeumer <1931590+dbaeumer@users.noreply.github.com> * Document TextDocumentSyncKind.None behavior for cell text synchronization Co-authored-by: dbaeumer <1931590+dbaeumer@users.noreply.github.com> * Document that notebook cell text sync follows textDocumentSync.change Instead of adding a new textContentSyncKind field, clarify in the documentation that notebook cell text documents follow the same synchronization behavior as specified by the server's textDocumentSync.change capability. Co-authored-by: dbaeumer <1931590+dbaeumer@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: dbaeumer <1931590+dbaeumer@users.noreply.github.com> Co-authored-by: Dirk Bäumer --- _specifications/lsp/3.17/notebookDocument/notebook.md | 8 ++++++++ _specifications/lsp/3.18/notebookDocument/notebook.md | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/_specifications/lsp/3.17/notebookDocument/notebook.md b/_specifications/lsp/3.17/notebookDocument/notebook.md index 216227a..a1916f5 100644 --- a/_specifications/lsp/3.17/notebookDocument/notebook.md +++ b/_specifications/lsp/3.17/notebookDocument/notebook.md @@ -234,6 +234,8 @@ The protocol will therefore support two modes when it comes to synchronizing cel * _cellContent_: in this mode only the cell text content is synchronized to the server using the standard `textDocument/did*` notification. No notebook document and no cell structure is synchronized. This mode allows for easy adoption of notebooks since servers can reuse most of it implementation logic. * _notebook_: in this mode the notebook document, the notebook cells and the notebook cell text content is synchronized to the server. To allow servers to create a consistent picture of a notebook document the cell text content is NOT synchronized using the standard `textDocument/did*` notifications. It is instead synchronized using special `notebookDocument/did*` notifications. This ensures that the cell and its text content arrives on the server using one open, change or close event. +In both modes, notebook cell text documents are treated as regular text documents. Therefore, they use the same synchronization mechanism as specified by the server's `textDocumentSync` capability. For the _notebook_ mode, the cell text content changes sent via `notebookDocument/didChange` follow the same full/incremental change format as `textDocument/didChange`, respecting the `TextDocumentSyncKind` specified in `textDocumentSync.change`. + To request the cell content only a normal document selector can be used. For example the selector `[{ language: 'python' }]` will synchronize Python notebook document cells to the server. However since this might synchronize unwanted documents as well a document filter can also be a `NotebookCellTextDocumentFilter`. So `{ notebook: { scheme: 'file', notebookType: 'jupyter-notebook' }, language: 'python' }` synchronizes all Python cells in a Jupyter notebook stored on disk. To synchronize the whole notebook document a server provides a `notebookDocumentSync` in its server capabilities. For example: @@ -505,6 +507,12 @@ export interface NotebookDocumentChangeEvent { /** * Changes to the text content of notebook cells. + * + * Cell text content changes follow the same synchronization mode + * as specified by the server's `textDocumentSync.change` capability. + * If `textDocumentSync.change` is `TextDocumentSyncKind.Incremental`, + * clients should send incremental updates. If it is + * `TextDocumentSyncKind.Full`, clients must send the full content. */ textContent?: { document: VersionedTextDocumentIdentifier; diff --git a/_specifications/lsp/3.18/notebookDocument/notebook.md b/_specifications/lsp/3.18/notebookDocument/notebook.md index 1ab6f41..912af93 100644 --- a/_specifications/lsp/3.18/notebookDocument/notebook.md +++ b/_specifications/lsp/3.18/notebookDocument/notebook.md @@ -252,6 +252,8 @@ The protocol will therefore support two modes when it comes to synchronizing cel * _cellContent_: in this mode, only the cell text content is synchronized to the server using the standard `textDocument/did*` notification. No notebook document and no cell structure is synchronized. This mode allows for easy adoption of notebooks since servers can reuse most of their implementation logic. * _notebook_: in this mode the notebook document, the notebook cells and the notebook cell text content is synchronized to the server. To allow servers to create a consistent picture of a notebook document, the cell text content is NOT synchronized using the standard `textDocument/did*` notifications. It is instead synchronized using special `notebookDocument/did*` notifications. This ensures that the cell and its text content arrive on the server using one open, change or close event. +In both modes, notebook cell text documents are treated as regular text documents. Therefore, they use the same synchronization mechanism as specified by the server's `textDocumentSync` capability. For the _notebook_ mode, the cell text content changes sent via `notebookDocument/didChange` follow the same full/incremental change format as `textDocument/didChange`, respecting the `TextDocumentSyncKind` specified in `textDocumentSync.change`. + To request the cell content, only a normal document selector can be used. For example, the selector `[{ language: 'python' }]` will synchronize Python notebook document cells to the server. However, since this might synchronize unwanted documents as well, a document filter can also be a `NotebookCellTextDocumentFilter`. So `{ notebook: { scheme: 'file', notebookType: 'jupyter-notebook' }, language: 'python' }` synchronizes all Python cells in a Jupyter notebook stored on disk. To synchronize the whole notebook document, a server provides a `notebookDocumentSync` in its server capabilities. For example: @@ -523,6 +525,12 @@ export interface NotebookDocumentChangeEvent { /** * Changes to the text content of notebook cells. + * + * Cell text content changes follow the same synchronization mode + * as specified by the server's `textDocumentSync.change` capability. + * If `textDocumentSync.change` is `TextDocumentSyncKind.Incremental`, + * clients should send incremental updates. If it is + * `TextDocumentSyncKind.Full`, clients must send the full content. */ textContent?: { document: VersionedTextDocumentIdentifier;