src/doc/en/installation/index.rst: Restructure Windows section as dec…

…ision tree
sagemath · Mar 11, 2024 · 318f5f3 · 318f5f3
1 parent 069fdd9
commit 318f5f3
Showing 1 changed file with 96 additions and 74 deletions.
diff --git a/src/doc/en/installation/index.rst b/src/doc/en/installation/index.rst
@@ -58,90 +58,47 @@ macOS
 Windows
 =======
 
-Approach 1: Use Visual Studio Code with SageMath dev containers
----------------------------------------------------------------
-
-`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.
-
-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.
-
-Note that 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/>`_.
+SageMath does not run natively on Windows. Using SageMath on this
+platform requires a virtualization method. Hence, as a first step:
 
 - 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.
 
-- `Download and install VS Code <https://code.visualstudio.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:**
+**Are you familiar with or interested in learning about using the Linux command line?**
 
-    - 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.
+- **Yes, Linux command line:**
 
-    - Create a subfolder named ``.devcontainer``. Download this file from the
-      SageMath GitHub repository and place it in this subfolder:
+  Then we recommend the method described in section
+  :ref:`installation-guide-windows-wsl` below.
 
-      - https://github.com/sagemath/sage/blob/develop/.devcontainer/downstream-conda-forge-latest/devcontainer.json
+  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.
 
-    - Use the command palette (:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`),
-      enter the command "Dev Containers: Reopen Folder in Container" , and hit :kbd:`Enter`.
+- **No, prefer to use Visual Studio Code:**
 
-      By clicking on "show log", you can see what it does; it will take a while.
+  Then we recommend the method described in section
+  :ref:`installation-guide-windows-devcontainers` below.
 
-    - To use Sage in a terminal, `open a new terminal in VS Code
-      <https://code.visualstudio.com/docs/terminal/basics>`_ and type ``sage``.
+  `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.
 
-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`.
+  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.
 
+.. _installation-guide-windows-wsl:
 
-Approach 2: Manual installation using Windows Subsystem for Linux
------------------------------------------------------------------
+Installing SageMath in the Windows Subsystem for 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
@@ -151,10 +108,6 @@ 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.
-
 - `Run the WSL install command as administrator.
   <https://learn.microsoft.com/en-us/windows/wsl/setup/environment#get-started>`_
   This will install Ubuntu Linux.
@@ -181,7 +134,7 @@ Start Ubuntu from the Start menu.
 
 -   **Yes, development:**
 
-    Then follow the instructions for development on Linux below.
+    Then follow the :ref:`instructions for development on Linux <installation-guide-linux>` below.
 
 -   **No development:**
 
@@ -208,6 +161,75 @@ To use Sage in a Jupyter notebook, it is convenient to use Visual Studio Code.
 See :ref:`sec-launching-vscode-wsl`.
 
 
+.. _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