API - How to create an "interactive"/REPL-style Notebook is not documented

[mobileskyfi]

VSCode added support for "Interactive Notebooks" (REPL-style, where the CLI is at bottom, cell outputs get stacked on top). Python notebooks use it, and the [rest-api] example also does too. And, I wanted to add support for a Notebook extension I'm working on.

While the docs are pretty good at giving an overview and pointing at sample for details. The docs do not touch on the topic of "Interactive Notebooks". While I got it working, the mechanisms to enable REPL in notebook extension are pretty wonky - docs cannot fix that – but all the more reason it should be documented better ;).

It took unwinding this diff:
tanhakabir/rest-book@c64a145

Along with the only doc I could find that had a couple more clues:
https://github.com/microsoft/vscode/wiki/Interactive-Window-Documentation

which isn't written for an extension author's POV.

AFAIK, the steps are:

• add onNotebook:interactive to package.json under activations along with the current notebook kernel, with "interactive" explicitly regardless of own extension naming.
• subscriptions.push() a second instance of extension's notebook NotebookController/"kernel" in activate(), except with notebookType : "interactive" and some derivative metadata:

  notebooks.createNotebookController(
            isInteractive ? `${this.controllerId}-repl` : this.controllerId,
            isInteractive ? "interactive" : this.notebookType,
            isInteractive ? `${this.label} REPL`: this.label
        );
  

• critically, to be able to get to you need add command (and file/open menu that invokes it) to extension for user to open it – with the command invoking the interactive.open command that provides the support (apparently):

  await commands.executeCommand('interactive.open',
    		undefined,
    		undefined,
    		`${exention-id}/${interactiveKernelControllerId}`,
    		undefined
    	);
  

It now looks simple, but this one took a while to unwind/figure out – thus the report. I missed that interactive.open was needed - the callback was off screen on a long line in rest-book example, and assumed it was called workspace.openNotebookDocument with the interactive type

Now I'm not sure that's the whole story on "Interactive Notebooks" - since it's not documented! So mere mention in docs would go a long way for the next person that tries to add a REPL notebook to an extension.