Document using Sage on Windows via Visual Studio Code with WSL remote

[mkoeppe]

We already have a basic VS Code configuration; #33103 makes some minor updates.

In this ticket, we add documentation for installing VS Code on Windows and setting up the WSL remote, as the primary way how to use Sage on Windows. This goes to

• https://doc.sagemath.org/html/en/installation/launching.html

Next task: cross reference it from the developer's guide and add information there on how to develop Sage on Windows.

References:

• Pylance: https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance (includes pyright)

Depends on #33131
Depends on #33103

CC: @tobiasdiez @EmmanuelCharpentier @sagetrac-tmonteil @kcrisman @louisng @kwankyu @tscrim @slel

Component: user interface

Author: Louis Ng, Matthias Koeppe

Branch/Commit: 79552c6

Reviewer: Tobias Diez, Kwankyu Lee

Issue created by migration from https://trac.sagemath.org/ticket/30484

[tobiasdiez]

comment:1

A basic how to setup VS code for sage (from #25206 comment:63):

• Start Visual Studio Code.
• Install "Remote-WSL" extension.
• Press F1, enter Remote-WSL: New Window, and hit enter.
• Use the File menu to open your folder.
• For running & debuging, follow ​https://code.visualstudio.com/remote-tutorials/wsl/edit-and-debug
• Use ./sage -br to trigger a rebuild of sage.

[mkoeppe]

comment:2

Should also add instructions for cygwin shell under VS code; random link - https://superuser.com/questions/1511487/cygwin-shell-in-vs-code-tries-to-activate-conda-how-to-prevent-this

[dimpase]

comment:4

Replying to @tobiasdiez:

• Use ./sage -br to trigger a rebuild of sage.

I'd suggest make build && ./sage instead.

[mkoeppe]

comment:5

Sage development has entered the release candidate phase for 9.3. Setting a new milestone for this ticket based on a cursory review of ticket status, priority, and last modification date.

[mkoeppe]

Dependencies: #30677

[mkoeppe]

Changed dependencies from #30677 to #33131, #33103

[dimpase]

comment:11

Hmm, I can't figure out how to use vscode with a Sage notebook.
The problem is to get vscode to find the correct kernel...

[tobiasdiez]

comment:12

At least for a "normal" jupyter notebook, selecting the venv created by sage worked for me.

There is also the possibility to connect to a "remote" jupyter instance. https://code.visualstudio.com/docs/datascience/jupyter-notebooks#_connect-to-a-remote-jupyter-server So if you start sage's jupyter server, you should be able to connect to it in this way.

[dimpase]

comment:13

Replying to @tobiasdiez:

At least for a "normal" jupyter notebook, selecting the venv created by sage worked for me.

The question is, how does vscode's jupyter discover kernels? Where?
What should be set?

There is also the possibility to connect to a "remote" jupyter instance. https://code.visualstudio.com/docs/datascience/jupyter-notebooks#_connect-to-a-remote-jupyter-server So if you start sage's jupyter server, you should be able to connect to it in this way.

[tobiasdiez]

comment:14

Attachment: Screenshot 2022-04-08 201448.png

In the upper right corner you can select the kernel/python version, see attached screenshot.

[louisng114]

comment:16

The link https://code.visualstudio.com/remote-tutorials/wsl/edit-and-debug does not seem to work.

[mkoeppe]

comment:17

Not sure if it has just moved or this is a different document: https://code.visualstudio.com/docs/remote/wsl

[mkoeppe]

comment:18

Or maybe this one: https://code.visualstudio.com/docs/remote/wsl-tutorial

[dimpase]

comment:19

Replying to @tobiasdiez:

In the upper right corner you can select the kernel/python version, see attached screenshot.

it's rather unpredictable whether Sage jupyter kernel will be available.
Often it's just not there. Perhaps it needs to installed to a specific location.

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

6881dd6

Changed phrasing regarding the command palette

[sagetrac-git]

Changed commit from 8a4eb05 to 6881dd6

[mkoeppe]

comment:26

On macOS, its Cmd + Shift + P. Perhaps also include the link to the VS Code documentation?

[tobiasdiez]

comment:27

Replying to @sagetrac-git:

Branch pushed to git repo; I updated commit sha1. New commits:

6881dd6

Changed phrasing regarding the command palette

Thanks!

[sagetrac-git]

Changed commit from 6881dd6 to b0c907e

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

b29ccb9	added VC Code WSL Jupyter section
8389ebc	Changed phrasing regarding the command palette
b0c907e	src/doc/en/installation/launching.rst: Add markup for key chords

[kwankyu]

comment:34

I am new to the Visual Studio Code interface to the sagemath installed in WSL.

I followed the guide of the branch of this ticket. It mostly worked.

But in the first attempt, I could not select SageMath kernel in the jupyter notebook. It was simply missing.

I wandered around for some time, and then found Jupyter Extension in the Extensions panel. I installed it, and did the ":Create: New Jupyter Notebook" thing again. Then I could finally select SageMath kernel.

So it seems that there is a missing step in the guide: "Install Jupyter Extension"

Anyway, this VSCode interface to sage is very nice!

Still it was not straightforward for me to setup the working jupyter notebook with sagemath kernel starting from building sage from source in WSL.

[mkoeppe]

comment:35

Thanks for testing it! I'll add this step

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

79552c6

src/doc/en/installation/launching.rst: Also mention Jupyter Extension

[sagetrac-git]

Changed commit from b0c907e to 79552c6

[mkoeppe]

Changed author from Louis Ng to Louis Ng, Matthias Koeppe

[kwankyu]

Changed reviewer from Tobias Diez to Tobias Diez, Kwankyu Lee

[kwankyu]

comment:38

Replying to @mkoeppe:

Thanks for testing it! I'll add this step

Thanks. It looks good to me.

[mkoeppe]

comment:42

Thanks!

[vbraun]

Changed branch from public/30484 to 79552c6