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

src/doc/en/installation/index.rst

@@ -21,9 +21,9 @@ SageMath release.
 macOS
 =====
 
-- **Do you want to do SageMath development?**
+**Do you want to do SageMath development?**
 
-  - **Yes, development:**
+-   **Yes, development:**
 
     Obtain the SageMath sources via ``git`` as described in `The Sage
     Developer's Guide
@@ -37,7 +37,7 @@ macOS
       these describe an experimental method that gets all required
       packages, including Python packages, from conda-forge.
 
-  - **No development:**
+-   **No development:**
 
     - Install the `binary build of SageMath <https://github.com/3-manifolds/Sage_macOS/releases>`_
       from the 3-manifolds project.  It is a signed and notarized app, which
@@ -58,73 +58,88 @@ macOS
 Windows
 =======
 
-- **Do you want to do SageMath development?**
+SageMath does not run natively on Windows. Using SageMath on this
+platform requires a virtualization method. Hence, as a first step:
 
-  - **Yes, development:**
+- Make sure that hardware-assisted virtualization is enabled in
+  the EFI or BIOS of your system. If in doubt, refer to your
+  system's documentation for instructions on how to do this.
 
-    Enable `Windows Subsystem for Linux (WSL)
-    <https://learn.microsoft.com/en-us/windows/wsl/>`_ and install
-    Ubuntu as follows.
 
-    - Make sure that hardware-assisted virtualization is enabled in
-      the EFI or BIOS of your system. If in doubt, refer to your
-      system's documentation for instructions on how to do this.
+**Are you familiar with or interested in learning about using the Linux command line?**
 
-    - `Run the WSL install command as administrator.
-      <https://learn.microsoft.com/en-us/windows/wsl/setup/environment#get-started>`_
-      This will install Ubuntu Linux.
+- **Yes, Linux command line:**
 
-      Note that the basic instructions in the linked article apply to
-      up-to-date installations of Windows 10 and 11, but there are
-      also links to the procedures for older builds of Windows 10.
+  Then we recommend the method described in section
+  :ref:`installation-guide-windows-wsl` below.
 
-    - If you had installed WSL previously or installed it using
-      different instructions, `verify that you are running WSL 2
-      <https://learn.microsoft.com/en-us/windows/wsl/install#check-which-version-of-wsl-you-are-running>`_.
+  This method is also a good choice if you are not interested in using
+  Visual Studio Code and if you want to have a persistent Sage
+  installation for use in several projects.
 
-    - `Set up your Linux username and password.
-      <https://learn.microsoft.com/en-us/windows/wsl/setup/environment#set-up-your-linux-username-and-password>`_
-      Do not include any spaces in your username.
+- **No, prefer to use Visual Studio Code:**
 
-    - If your computer has less than 10GB of RAM, `change the WSL settings
-      <https://learn.microsoft.com/en-us/windows/wsl/wsl-config#main-wsl-settings>`_
-      to make at least 5GB of RAM available to WSL.
+  Then we recommend the method described in section
+  :ref:`installation-guide-windows-devcontainers` below.
 
-    Start Ubuntu from the Start menu. Then follow the instructions for
-    development on Linux below.
+  `Visual Studio Code <https://code.visualstudio.com/>`_ is a popular
+  and powerful code editor developed by Microsoft and made available
+  free of charge. We recommmend it because of a key feature, the `Visual
+  Studio Code Dev Containers extension
+  <https://code.visualstudio.com/docs/devcontainers/containers>`_, which
+  provides a very convenient way to install and use SageMath running in
+  a Linux container.
 
-  - **No development:**
+  We recommend this installation method in particular to users who are not already
+  familiar with Windows Subsystem for Linux. It is also suitable for machines that
+  cannot run WSL 2 (because of hardware constraints or policy set by system
+  administrators) but can run Docker.
 
-    Enable `Windows Subsystem for Linux (WSL)
-    <https://learn.microsoft.com/en-us/windows/wsl/>`_ and install
-    Ubuntu as follows.
+.. _installation-guide-windows-wsl:
 
-    - Make sure that hardware-assisted virtualization is enabled in
-      the EFI or BIOS of your system. If in doubt, refer to your
-      system's documentation for instructions on how to do this.
+Installing SageMath in the Windows Subsystem for Linux
+------------------------------------------------------
 
-    - `Run the WSL install command as administrator.
-      <https://learn.microsoft.com/en-us/windows/wsl/setup/environment#get-started>`_
-      This will install Ubuntu Linux.
+We recommend this installation method in particular to users who are already
+familiar with Linux or Windows Subsystem for Linux. It is also a good choice if
+you want to have a persistent Sage installation for use in several projects.
 
-      Note that the basic instructions in the linked article apply to
-      up-to-date installations of Windows 10 and 11, but there are
-      also links to the procedures for older builds of Windows 10.
+Enable `Windows Subsystem for Linux (WSL)
+<https://learn.microsoft.com/en-us/windows/wsl/>`_ and install
+Ubuntu as follows.
 
-    - If you had installed WSL previously or installed it using
-      different instructions, `verify that you are running WSL 2
-      <https://learn.microsoft.com/en-us/windows/wsl/install#check-which-version-of-wsl-you-are-running>`_.
+- `Run the WSL install command as administrator.
+  <https://learn.microsoft.com/en-us/windows/wsl/setup/environment#get-started>`_
+  This will install Ubuntu Linux.
 
-    - `Set up your Linux username and password.
-      <https://learn.microsoft.com/en-us/windows/wsl/setup/environment#set-up-your-linux-username-and-password>`_
-      Do not include any spaces in your username.
+  Note that the basic instructions in the linked article apply to
+  up-to-date installations of Windows 10 and 11, but there are
+  also links to the procedures for older builds of Windows 10.
 
-    - If your computer has less than 8GB of RAM, `change the WSL settings
-      <https://learn.microsoft.com/en-us/windows/wsl/wsl-config#main-wsl-settings>`_
-      to make at least 4GB of RAM available to WSL.
+- If you had installed WSL previously or installed it using
+  different instructions, `verify that you are running WSL 2
+  <https://learn.microsoft.com/en-us/windows/wsl/install#check-which-version-of-wsl-you-are-running>`_.
 
-    Start Ubuntu from the Start menu, and type the following commands
-    to install Sage from conda-forge. (The ``$`` represents the command
+- `Set up your Linux username and password.
+  <https://learn.microsoft.com/en-us/windows/wsl/setup/environment#set-up-your-linux-username-and-password>`_
+  Do not include any spaces in your username.
+
+- If your computer has less than 10GB of RAM, `change the WSL settings
+  <https://learn.microsoft.com/en-us/windows/wsl/wsl-config#main-wsl-settings>`_
+  to make at least 5GB of RAM available to WSL.
+
+Start Ubuntu from the Start menu.
+
+**Do you want to do SageMath development?**
+
+-   **Yes, development:**
+
+    Then follow the :ref:`instructions for development on Linux <installation-guide-linux>` below.
+
+-   **No development:**
+
+    Type the following commands to install Sage from conda-forge.
+    (The ``$`` represents the command
     line prompt, don't type it!) The second step will ask a few questions,
     and you may need to hit :kbd:`Enter` to confirm or type ``yes``
     and then hit :kbd:`Enter`.
@@ -151,14 +166,83 @@ Windows
     in particular for setting up the Jupyter notebook, which is required if
     you want to use graphics.
 
+.. _installation-guide-windows-devcontainers:
+
+Using Visual Studio Code with SageMath dev containers
+-----------------------------------------------------
+
+- `Download and install VS Code <https://code.visualstudio.com/>`_.
+
+  .. note::
+
+     Although the source code of VS Code is open source (MIT
+     License), the Dev Containers extension is only known to work with the
+     Visual Studio Code product, but not with fully open source builds such
+     as `VSCodium <https://vscodium.com/>`_.
+
+- In VS Code, if the `Visual Studio Code Dev Containers
+  <https://code.visualstudio.com/docs/devcontainers/containers>`_ extension
+  is not already installed, click the "Extension" icon on the left
+  (or press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`X`) to open a list of
+  extensions. Search for "Dev Containers" and install it.
+
+  The extension will walk you through the installation of Docker
+  Desktop and activating Windows Subsystem for Linux (WSL 2).
+
+**Do you want to do SageMath development?**
+
+-   **Yes, development:**
+
+    - In VS Code, `clone
+      <https://code.visualstudio.com/docs/editor/versioncontrol#_cloning-a-repository>`_
+      the `SageMath git repository
+      <https://github.com/sagemath/sage>`_. For example, use the VS Code
+      Command Palette (:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`), enter the
+      command "Git: Clone", hit :kbd:`Enter`, paste the URL https://github.com/sagemath/sage
+      and hit :kbd:`Enter` again.
+
+    - Use the command palette (:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`),
+      enter the command "Dev Containers: Reopen Folder in Container" , and hit :kbd:`Enter`.
+
+      By clicking on "show log", you can see what it does; it will take a while.
+
+    - To use Sage in a terminal, `open a new terminal in VS Code
+      <https://code.visualstudio.com/docs/terminal/basics>`_ and type ``./sage``.
+
+-   **No development:**
+
+    - Open the folder of a project where you would like to use Sage in VS Code, or
+      just create a new folder for your work with Sage.
+
+    - Create a subfolder named ``.devcontainer``. Download this file from the
+      SageMath GitHub repository and place it in this subfolder:
+
+      - https://github.com/sagemath/sage/blob/develop/.devcontainer/downstream-conda-forge-latest/devcontainer.json
+
+    - Use the command palette (:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`),
+      enter the command "Dev Containers: Reopen Folder in Container" , and hit :kbd:`Enter`.
+
+      By clicking on "show log", you can see what it does; it will take a while.
+
+    - To use Sage in a terminal, `open a new terminal in VS Code
+      <https://code.visualstudio.com/docs/terminal/basics>`_ and type ``sage``.
+
+To use Sage in a Jupyter notebook, click the "Extension" icon on the left (or press
+:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`X`) to open a list of
+extensions. Install the "Jupyter" extension. In the command
+palette, enter "Create: New Jupyter Notebook", and hit
+:kbd:`Enter`. Click "Select Kernel" on the right (or press :kbd:`Ctrl` +
+:kbd:`Alt` + :kbd:`Enter`), select SageMath, and hit :kbd:`Enter`.
+
+
 .. _installation-guide-linux:
 
 Linux
 =====
 
-- **Do you want to do SageMath development?**
+**Do you want to do SageMath development?**
 
-  - **Yes, development:**
+-   **Yes, development:**
 
     Obtain the SageMath sources via ``git`` as described in `The Sage
     Developer's Guide
@@ -172,7 +256,7 @@ Linux
       these describe an experimental method that gets all required
       packages, including Python packages, from conda-forge.
 
-  - No development: **Do you have root access (sudo)?**
+-   No development: **Do you have root access (sudo)?**
 
     - **Yes, root access:** Then the easiest way to install SageMath is
       through a Linux distribution that provides it as a package.  Some
@@ -209,7 +293,8 @@ In the cloud
   <https://hub.docker.com/r/sagemathinc/cocalc>`_ can be used on any system with Docker to run CoCalc locally.
 
 
-More information:
+More information
+================
 
 .. toctree::
    :maxdepth: 2

src/doc/en/installation/launching.rst

@@ -278,6 +278,8 @@ You can check the presence of some of these packages using the command
 
      plot3d(lambda u,v:(u^2+v^2)/4-2,(-2,2),(-2,2)).show(viewer="jmol")
 
+.. _sec-launching-vscode-wsl:
+
 Using Jupyter notebook through Visual Studio Code (VS Code) in WSL
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 

src/doc/en/installation/source.rst

@@ -453,7 +453,7 @@ Installation steps
 
    You should see the Sage prompt, which will look something like this::
 
-       $ sage
+       $ ./sage
        ┌────────────────────────────────────────────────────────────────────┐
        │ SageMath version 8.8, Release Date: 2019-06-26                     │
        │ Using Python 3.10.4. Type "help()" for help.                       │