Improve Windows installation instructions

README.md

@@ -78,10 +78,11 @@ mailing list](https://groups.google.com/group/sage-devel).
 [Windows] Preparing the Platform
 --------------------------------
 
-The preferred way to run Sage on Windows is using the [Windows Subsystem for
-Linux](https://docs.microsoft.com/en-us/windows/wsl/faq), a.k.a. WSL, which allows
-you to install a standard Linux distribution such as Ubuntu within
-your Windows. Make sure you allocate WSL sufficient RAM; 5GB is known to work, while
+The preferred way to run Sage on Windows is using Windows Subsystem for
+Linux (WSL). Follow the
+[official WSL setup guide](https://docs.microsoft.com/en-us/windows/wsl/faq)
+to install Ubuntu (or another Linux distribution).
+Make sure you allocate WSL sufficient RAM; 5GB is known to work, while
 2GB might be not enough for building Sage from source.
 Then all instructions for installation in Linux apply.
 

src/doc/en/installation/conda.rst

@@ -9,32 +9,27 @@ SageMath can be installed on Linux and macOS via Conda from the
 Both the ``x86_64`` (Intel) architecture and the ``arm64``/``aarch64``
 architectures (including Apple Silicon, M1) are supported.
 
-You will need a working Conda installation: either Mambaforge/Miniforge,
+You will need a working Conda installation: either Miniforge (or Mambaforge),
 Miniconda or Anaconda. If you don't have one yet, we recommend installing
-`Mambaforge <https://github.com/conda-forge/miniforge#mambaforge>`_ as
+`Miniforge <https://github.com/conda-forge/miniforge>`_ as
 follows. In a terminal,
 
 .. code-block:: shell
 
-   $ curl -L -O https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-$(uname)-$(uname -m).sh
-   $ sh Mambaforge-$(uname)-$(uname -m).sh
+   $ curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
+   $ bash Miniforge3-$(uname)-$(uname -m).sh
 
-* Mambaforge and Miniforge use conda-forge as the default channel.
+* Miniforge (and Mambaforge) use conda-forge as the default channel.
 
 * If you are using Miniconda or Anaconda, set it up to use conda-forge:
 
   * Add the conda-forge channel: ``conda config --add channels conda-forge``
 
   * Change channel priority to strict: ``conda config --set channel_priority strict``
 
-Optionally, use `mamba <https://github.com/mamba-org/mamba>`_,
+If you installed Miniforge (or Mambaforge), we recommend to use 
+`mamba <https://mamba.readthedocs.io/en/latest/index.html>`_ in the following, 
 which uses a faster dependency solver than ``conda``.
-If you installed Mambaforge, it is already provided. Otherwise, use
-
-.. code-block:: shell
-
-   $ conda install mamba
-
 
 .. _sec-installation-conda-binary:
 
@@ -43,10 +38,17 @@ Installing all of SageMath from conda (not for development)
 
 Create a new conda environment containing SageMath, either with ``mamba`` or ``conda``:
 
-.. code-block:: shell
+.. tab:: mamba
+
+  .. code-block:: shell
 
-    $ mamba create -n sage sage python=X        # either
-    $ conda create -n sage sage python=X        # or
+      $ mamba create -n sage sage python=X
+
+.. tab:: conda
+
+  .. code-block:: shell
+
+      $ conda create -n sage sage python=X
 
 where ``X`` is version of Python, e.g. ``3.9``.
 
@@ -109,17 +111,22 @@ Here we assume that you are using a git checkout.
 
       $ export SAGE_NUM_THREADS=24
 
-  - As a recommended step, install the ``mamba`` package manager. If
-    you skip this step, replace ``mamba`` by ``conda`` in the
-    following steps::
-
-      $ conda install mamba
-
   - Create and activate a new conda environment with the dependencies of Sage
     and a few additional developer tools::
 
-      $ mamba env create --file src/environment-dev-3.11-linux.yml --name sage-dev
-      $ conda activate sage-dev
+      .. tab:: mamba
+
+        .. code-block:: shell
+
+            $ mamba env create --file src/environment-dev-3.11-linux.yml --name sage-dev
+            $ conda activate sage-dev
+
+      .. tab:: conda
+
+        .. code-block:: shell
+
+            $ conda env create --file src/environment-dev-3.11-linux.yml --name sage-dev
+            $ conda activate sage-dev
 
     Alternatively, you can use ``src/environment-3.11-linux.yml`` or
     ``src/environment-optional-3.11-linux.yml``, which will only install standard

src/doc/en/installation/index.rst

@@ -16,6 +16,8 @@ SageMath release.
 
 **Where would you like to run SageMath?** Pick one of the following sections.
 
+.. _installation-guide-macos:
+
 macOS
 =====
 
@@ -51,38 +53,105 @@ macOS
     - Alternatively, build SageMath from source as described in section
       :ref:`sec-installation-from-sources`.
 
+.. _installation-guide-windows:
+
 Windows
 =======
 
 - **Do you want to do SageMath development?**
 
   - **Yes, development:**
 
-    Enable Windows Subsystem for Linux (WSL) by following the
-    `official WSL setup guide
-    <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_. Be
-    sure to do the steps to install WSL2 and set it as default.
-    Make sure to allocate enough RAM to WSL: 5GB is known to be enough,
-    2GB might not allow you to build some packages.
-    Then go to the Microsoft Store and install Ubuntu (or another
-    Linux distribution). Start Ubuntu from the start menu.
+    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.
+
+      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 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>`_.
 
-    Then follow the instructions for development on Linux below.
+    - `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. Then follow the instructions for
+    development on Linux below.
 
   - **No development:**
 
-    Enable Windows Subsystem for Linux (WSL) by following the
-    `official WSL setup guide
-    <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_. Be
-    sure to do the steps to install WSL2 and set it as default.
-    Make sure to allocate enough RAM to WSL: 5GB is known to be enough,
-    2GB might not allow you to build some packages.
-    Then go to the Microsoft Store and install Ubuntu (or another
-    Linux distribution). Start Ubuntu from the start menu.
-
-    On the Linux running on WSL, you always have root access, so you
-    can use any of the installation methods described below for
-    Linux.
+    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.
+
+      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 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>`_.
+
+    - `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 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.
+
+    Start Ubuntu from the Start menu, and 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`.
+
+    .. code-block:: shell
+
+       $ curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
+       $ bash Miniforge3-$(uname)-$(uname -m).sh
+       $ conda create -n sage sage python=3.11
+
+    (If there are any installation failures, please report them to
+    the conda-forge maintainers by opening a `GitHub Issue for
+    conda-forge/sage-feedstock <https://github.com/conda-forge/sage-feedstock/issues>`_.)
+
+    You can now start SageMath as follows:
+
+    .. code-block:: shell
+
+       $ conda activate sage
+       $ sage
+
+    This way of starting Sage gives you the most basic way of using
+    Sage in the terminal. See :ref:`sec-launching` for recommended next steps,
+    in particular for setting up the Jupyter notebook, which is required if
+    you want to use graphics.
+
+.. _installation-guide-linux:
 
 Linux
 =====

src/doc/en/installation/source.rst

@@ -264,24 +264,10 @@ WSL prerequisites
 Ubuntu on Windows Subsystem for Linux (WSL) prerequisite installation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Sage can be installed onto Linux running on Windows Subsystem for Linux (WSL). These instructions describe a fresh install of Ubuntu 20.10, but other distributions or installation methods should work too, though have not been tested.
-
-- Enable hardware-assisted virtualization in the EFI or BIOS of your system. Refer to your system (or motherboard) maker's documentation for instructions on how to do this.
-
-- Set up WSL by following the `official WSL setup guide <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_. Be sure to do the steps to install WSL2 and set it as default.
-
-- Go to the Microsoft Store and install Ubuntu.
-
-- Start Ubuntu from the start menu. Update all packages to the latest version.
-
-- Reboot the all running WSL instances one of the following ways:
-
-  - Open Windows Services and restart the LxssManager service.
-  - Open the Command Prompt or Powershell and enter this command::
-
-      wsl --shutdown
-
-- `Upgrade to the Ubuntu 20.10 <https://linuxconfig.org/how-to-upgrade-ubuntu-to-20-10>`_. This step will not be necessary once Ubuntu 20.10 is available in the Microsoft Store.
+Refer to :ref:`installation-guide-windows` for installing Ubuntu on
+Windows Subsystem for Linux (WSL). These instructions describe a fresh
+install of Ubuntu, the default distribution in WSL, but other
+distributions or installation methods should work too.
 
 From this point on, follow the instructions in the :ref:`sec-installation-from-sources-linux-recommended-installation` section.
 It is strongly recommended to put the Sage source files in the Linux file system, for example, in the ``/home/username/sage`` directory, and not in the Windows file system (e.g. ``/mnt/c/...``).