Docs: add a VS Code Run On Save setup for ipynb-to-py

[TTTPOB]

Use case

When editing notebooks in VS Code, j-cli convert ipynb-to-py can keep a same-name py:percent file updated whenever an existing .ipynb file is saved. This makes the notebook the source of truth while keeping the paired .py file available for review and text-based tooling.

Setup

Install the emeraldwalk/vscode-runonsave extension and add this workspace setting to .vscode/settings.json:

{
  "emeraldwalk.runonsave": {
    "ignoreUnchangedFiles": true,
    "commands": [
      {
        "match": "\\.ipynb$",
        "cmd": "j-cli convert ipynb-to-py \"${file}\" \"${fileDirname}/${fileBasenameNoExt}.py\"",
        "autoShowOutputPanel": "error"
      }
    ]
  }
}

The extension matches match against the absolute saved-file path. Its placeholders map the input notebook to a .py file in the same directory. Quoting both paths supports spaces in directory and file names.

Result

Saving path/to/analysis.ipynb runs:

j-cli convert ipynb-to-py "path/to/analysis.ipynb" "path/to/analysis.py"

The command runs synchronously by default. When conversion fails, autoShowOutputPanel: "error" opens the Run On Save output panel.

Caveats

• j-cli must be available on the PATH inherited by VS Code.
• Run On Save only reacts when an existing file is saved. Creating a notebook or using Save As does not trigger it; save the resulting file once more.
• This is a one-way workflow: each notebook save overwrites the paired .py source. It should only be recommended when the .ipynb file is the source of truth.
• Workspace settings keep the behavior scoped to the current project. Teams can commit .vscode/settings.json, while individual users can ignore it locally.

It would be useful to include this as an optional VS Code workflow in the conversion documentation.