Better API to associate a notebook cell document with its notebook

[jrieken]

A notebook document contains cell documents, which are vscode.TextDocument types. There is no easy/nice way to get to a notebook from a document. Ideas

• add a util like notebook.findContainerNotebook(document: TextDocument): NotebookDocument | undefined
• add a pointer from the document, e.g TextDocument#notebook: NotebookDocument | undefined

[jrieken]

fyi @rebornix

[jrieken]

Closing, the proposal is done but currently unused. We'll see if we keep this when finalizing the whole API

[jrieken]

• Relation is: text document to notebook cell (not notebook itself)
• Challenge: text document doesn't own the cell
• Maybe: explicit find function might be better

[DonJayamanne]

@jrieken Thought I'd let u know how I'm using this today in my personal extensions:

• In Kusto notebook extension
  • I use this in completions provider, I need a way to determine whether a text document belongs to a Notebook document or not (and then get information about that notebook document/metadata).
  • Toady when documents are opened (even triggered for notebook cells), i get the corresponding notebook information of the associated cell, I send this information to the language server
  • Now the language server can map the text Uri back to a notebook (if it is a cell text document)
• In an extension for Jupyter notebooks
  • I change the language of cells based on the contents of the cell (e.g. if cell has %kql, then I change the language of that cell from Python to to kusto (again, this can only be done if I know for a fact this text document belongs to a Notebook cell)
• Also using in another editor to add line/column numbers for cell statusbar.

For all of these, I also need the window.activeNotebookEditor API (which too is a proposed API).

[jrieken]

The plan is to replace TextDocument#notebook: NotebookDocument | undefined with a util-function because (a) the reference would be text document to notebook cell (not notebook) and (b) it is a bit of a weird reference cycle because the cell is composed of the text document and other properties and these "child properties" usually don't point to the container.

[jrieken]

Idea/sketch:

namespace notebooks {
  /**
   * @returns A notebook cell which contents are represented by the given text document
   */
  export function getNotebookCell(textDocument: TextDocument): NotebookCell | undefined;
}