Installation Guide: Document Sage installation on Windows via VS Code dev containers

[mkoeppe]

Preview: https://doc-pr-37534--sagemath.netlify.app/html/en/installation/#using-visual-studio-code-with-sagemath-dev-containers

• Rebased and updated version of Installation guide: Document Sage installation on Windows via VS Code devcontainers #34363

Fixes #34363

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion.
• I have created tests covering the changes.
• I have updated the documentation accordingly.

⌛ Dependencies

• Depends on Improve Windows installation instructions #37184
• Depends on Update Conda installation instructions to use Miniforge #37588

[mkoeppe]

@kcrisman If you are able to get another time allotment on the household supercomputer...

[kcrisman]

Wow, this looks ridiculously more complicated than the other method. Even for people with less Linux experience. Are we sure this should be the first method suggested? Note the several dense paragraphs (including one about licenses) before even getting to the virtualization bullet point.

On a more specific note, "The extension will walk you through the installation of Docker Desktop and activating Windows Subsystem for Linux (WSL 2)." but the change earlier says this is specifically for people who can't use WSL.

---

Even less related, but convenient to put here since the other ticket is baked, I note that while we have the useful sections now, it just says "Pick one of the following sections." Maybe there should be a very brief rst list there for people to click through to. The list as it stands is getting a bit long for convenience, so that would be helpful (not necessarily on this ticket).

---

Also, for anyone reading this, see the long discussion at #34363 which, however, failed to enlighten me as to which approach is actually better for non-POSIX-familiar Windows users. My gut says that "very explicit instructions which don't require many downloads and extensions" is going to be better than "links to download a lot of other stuff and then install it, plus Command Palettes and making a subfolder named .devcontainer." It would take some experimentation to see which one is actually better. I do think it's fine if both of them are documented, to be clear, and I'm certainly glad that we don't need Cygwin and other such solutions any more (though props to those who spent so many hours making those solutions work!).

[mkoeppe]

this looks ridiculously more complicated than the other method. Even for people with less Linux experience. Are we sure this should be the first method suggested?

I honestly don't know. This hasn't been field-tested.

[mkoeppe]

Even less related, but convenient to put here since the other ticket is baked, I note that while we have the useful sections now, it just says "Pick one of the following sections." Maybe there should be a very brief rst list there for people to click through to.

I'll do that at here for the two sections.

[kcrisman]

I'll do that at here for the two sections.

Having the list for Mac, Windows, Linux (three sections) would be particularly useful. (Maybe I misread what you intended with "two sections"?)

[kcrisman]

I honestly don't know. This hasn't been field-tested.

Okay, probably we should test it first then (which you already asked for) and I may report back. Just going with my hunch on this so far.

[mkoeppe]

I'll do that at here for the two sections.

Having the list for Mac, Windows, Linux (three sections) would be particularly useful. (Maybe I misread what you intended with "two sections"?)

I meant for the two subsections of the Windows section. (Done in f97b622.)

[jhpalmieri]

I am writing as a representative of the Sage Conduct Committee to record a -1 vote from Tobias.

[kcrisman]

I am writing as a representative of the Sage Conduct Committee to record a -1 vote from Tobias.

Hi, can you clarify if that means "-1 for this PR to be merged in the current form", in which case some rationale would be helpful, or does that mean something else? I'm trying to get up to speed with the whirlwind changes around the Conduct business 😦 sorry, appreciate the clarification.

[mkoeppe]

Whatever the process, it is important that other reviewers do not feel intimidated by it.

[jhpalmieri]

I am writing as a representative of the Sage Conduct Committee to record a -1 vote from Tobias.

Hi, can you clarify if that means "-1 for this PR to be merged in the current form", in which case some rationale would be helpful, or does that mean something else? I'm trying to get up to speed with the whirlwind changes around the Conduct business 😦 sorry, appreciate the clarification.

It means that, to the extent that the PR is disputed, this is one vote against merging it (re the discussion/vote in sage-devel about disputed tickets). I have asked Tobias to contact you, Karl-Dieter, as someone involved in the ticket, to communicate more details. (The vote of "-1" was received before some of the changes to the PR, for what that's worth.)

[kcrisman]

It means that, to the extent that the PR is disputed, this is one vote against merging it (re the discussion/vote in sage-devel about disputed tickets). I have asked Tobias to contact you, Karl-Dieter, as someone involved in the ticket, to communicate more details. (The vote of "-1" was received before some of the changes to the PR, for what that's worth.) Thanks, I'm starting to get up to speed with that now. I suspect that

some of the changes will support that. I may make a comment on the relevant thread, thanks.

…

Message ID: ***@***.***>

[kcrisman]

I am writing as a representative of the Sage Conduct Committee to record a -1 vote from Tobias.

Hi, can you clarify if that means "-1 for this PR to be merged in the current form", in which case some rationale would be helpful, or does that mean something else?

Followup: In this comment some of that was explained, and indeed agrees with my suspicion that this is a pretty onerous way to install. Unfortunately I didn't have time to try it out on Windows this weekend, and this week looks bad too, but I would like to verify that it works (and how easy it is by comparison) before formally committing to that.

[mkoeppe]

Thanks @kcrisman. There's no urgency here, this one for sure won't make it into Sage 10.3.

Regarding the usability of this approach, it is best if it is independently tried by several people.

I have another PR in prep as a follow-up: #37541, which would replace the awkward step of copying files from the repo by hand.

[github-actions]

Documentation preview for this PR (built with commit aea368e; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

[soehms]

Wow, this looks ridiculously more complicated than the other method. Even for people with less Linux experience. Are we sure this should be the first method suggested? Note the several dense paragraphs (including one about licenses) before even getting to the virtualization bullet point.

On a more specific note, "The extension will walk you through the installation of Docker Desktop and activating Windows Subsystem for Linux (WSL 2)." but the change earlier says this is specifically for people who can't use WSL.

Even less related, but convenient to put here since the other ticket is baked, I note that while we have the useful sections now, it just says "Pick one of the following sections." Maybe there should be a very brief rst list there for people to click through to. The list as it stands is getting a bit long for convenience, so that would be helpful (not necessarily on this ticket).

Also, for anyone reading this, see the long discussion at #34363 which, however, failed to enlighten me as to which approach is actually better for non-POSIX-familiar Windows users. My gut says that "very explicit instructions which don't require many downloads and extensions" is going to be better than "links to download a lot of other stuff and then install it, plus Command Palettes and making a subfolder named .devcontainer." It would take some experimentation to see which one is actually better. I do think it's fine if both of them are documented, to be clear, and I'm certainly glad that we don't need Cygwin and other such solutions any more (though props to those who spent so many hours making those solutions work!).

I competely share these apprehensions. I went through the instructions and I found it much harder as installing and using Sage directly under WSL (see #37029 (comment)). If we declare this as the default installation method on Windows, then we send people with no development experiences into the jungle even though they are just interested in one tree. For these people that would be rather repulsive and frustrating.

I think it would by much easier (still not easy) to save people from installing VS Code and let them run Sage directly in Docker-Desktop (which needs to be installed for VS Code, too). The difficulty then, of course, is copying files from the Windows file system to the container and back. Is there a way to make this more convenient for example by implementing a Docker-Desktop extension for Sage?

Another option could be to use appropriate Docker commands (for example the mount option) in specific entry and closing scripts within a Windows bash (or powershell to reduce requirements) terminal. Of course, this way we could also simplify the use of the native WSL approach.