Trac #31138: Document WSL Installation

In reponse to an [https://ask.sagemath.org/question/53294/installing-
optional-packages-infinite-loop/#54977 ask.sagemath question] about
package installation on windows, I linked to my documentation for a
from-source installation on WSL.

Emmanuel Charpentier requested that I added this to the official
documentation.

I've added a section on setting up WSL to en/installation/source.rst and
a section which covers the steps needed to launch sage in WSL from the
windows desktop or start menu to en/installation/launching.rst

URL: https://trac.sagemath.org/31138
Reported by: gh-sandyscott
Ticket author(s): Sandy Scott
Reviewer(s): Tobias Diez

Author: Release Manager

src/doc/en/installation/launching.rst

@@ -48,6 +48,69 @@ Note that this assumes that a firewall which might be present between server
 and client allows connections on port 8888. See details on port forwarding on
 the internet, e.g. https://www.ssh.com/ssh/tunneling/example.
 
+.. _sec-launching-wsl-post-installation:
+
+WSL Post-installation steps
+---------------------------
+
+If you've installed Sage Math from source on WSL, there are a couple of extra steps you can do to make your life easier:
+
+Create a notebook launch script
+"""""""""""""""""""""""""""""""
+
+If you plan to use JupyterLab, install that first.
+
+Now create a script called ``~/sage_nb.sh`` containing the following lines, and fill in the correct paths for your desired starting directory and ``SAGE_ROOT``
+
+
+.. CODE-BLOCK:: bash
+
+    #!/bin/bash
+    # Switch to desired windows directory
+    cd /mnt/c/path/to/desired/starting/directory
+    # Start the Jupyter notebook
+    SAGE_ROOT/sage --notebook
+    # Alternatively you can run JupyterLab - delete the line above, and uncomment the line below
+    #SAGE_ROOT/sage --notebook jupyterlab
+
+Make it executable:
+
+.. CODE-BLOCK:: bash
+
+    chmod ug+x ~/sage_nb.sh
+
+Run it to test:
+
+.. CODE-BLOCK:: bash
+
+    cd ~
+    ./sage_nb.sh
+
+The Jupyter(Lab) server should start in the terminal window, and you windows browser should open a page showing the Jupyter or JupyterLab starting page, at the directory you specified.
+
+Create a shortcut
+"""""""""""""""""
+
+This is a final nicety that lets you start the Jupyter or JupyterLab server in one click:
+
+* Open Windows explorer, and type ``%APPDATA%\Microsoft\Windows\Start Menu\Programs`` in the address bar and press enter. This is the folder that contains you start menu shortcuts. If you want the sage shortcut somewhere else (like your desktop), open that folder instead.
+* Open a separate window and go to ``%LOCALAPPDATA%\Microsoft\WindowsApps\``
+* Right-click-drag the ``ubuntu.exe`` icon from the second window into the first, then choose ``Create shortcuts here`` from the context menu when you drop it. 
+* To customize this shortcut, right-click on it and choose properties.
+
+  * On the General tab:
+
+    * Change the name to whatever you want, e.g. "Sage 9.2 JupyterLab"
+  
+  * On the Shortcut tab:
+
+    * Change Target to: ``ubuntu.exe run ~/sage_nb.sh``
+    * Change Start in to: ``%USERPROFILE%``
+    * Change Run to: Minimised
+    * Change the icon if you want
+
+Now hit the start button or key and type the name you gave it. it should appear in the list, and should load the server and fire up your browser when you click on it.
+
 ------------------------------------------------------------------------
 
 For further reading you can have a look at the other documents in the

src/doc/en/installation/source.rst

@@ -229,6 +229,8 @@ on the command line. If it gives an error (or returns nothing), then
 either ``perl`` is not installed, or it is installed but not in your
 `PATH <https://en.wikipedia.org/wiki/PATH_%28variable%29>`_.
 
+.. _sec-installation-from-sources-linux-recommended-installation:
+
 Linux recommended installation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -401,6 +403,32 @@ include:
 
 .. literalinclude:: cygwin-optional.txt
 
+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 distibutions 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.
+
+From this point on, follow the instructions in the :ref:`sec-installation-from-sources-linux-recommended-installation` section.
+
+When the installation is complete, you may be interested in :ref:`sec-launching-wsl-post-installation`.
+
 Other platforms
 ^^^^^^^^^^^^^^^
 
@@ -1613,4 +1641,4 @@ the directory where you want to install Sage.
 
 
 
-**This page was last updated in May 2020 (Sage 9.1).**
+**This page was last updated in December 2020 (Sage 9.3).**