docs: streamline tutorials, add and update how-to guides (#860)

UDENG-3595

This PR makes several significant changes to the structure and content
of the UP4W tutorial and the how-to sections of the docs.

The tutorial has been greatly simplified and shortened to focus on
installation, adding a Pro token and verifying Pro attachment. There are
now an increased number of short how-to guides that aim to be brief and
reliable sets of instructions for specific tasks.

Tabbed interfaces are used when presenting alternate configuration
options for ease-of-navigation.

Major changes:

- **Decoupling of UP4W and Landscape:** installation and automatic
Pro-attachment with UP4W does not depend on Landscape. The Getting
Started tutorial now only covers the process of installing UP4W,
configuring Pro and verifying Pro attachment. The tutorial should now be
easier to navigate successfully for a first-time user interested in
automatic Pro-attachment of Ubuntu WSL instances. This decoupling is
also reflected in the how-to guides, which now treat adding a Pro token
and configuring Landscape as independent tasks.
- **Simplification of installation how-to guide:** the original how-to
guide on installation and configuration consisted of several dropdown
menus, callout blocks and caveats, making it quite difficult to follow
for a task that should be straightforward. It has been simplified, in
part by presenting a tabbed interface with the two primary options for
installing with Windows registry and installing with the graphical
Windows application.
- **Extraction of short how-to guides from tutorial content:** another
reason for the length of the original tutorial was the inclusion of
sections relating to backing up instances and uninstalling applications.
These have been extracted into self-contained how-to guides as they
contain useful information that a user is likely to return to for a
variety of reasons in the context of Ubuntu WSL in general. They are
referenced in the tutorial but are not fully included to avoid breaking
up the flow of the tutorial.
- **Updated guidelines on Landscape config:** the Landscape integration
with UP4W has undergone some changes, particularly with respect to the
UI. The documentation now reflects these changes.
- **Increased elaboration of Windows registry option:** using the
Windows registry is an important option for enterprise users. It is now
given increased prominence in the documentation with some additional
text explaining why it is useful and images for user instruction. The
getting started tutorial uses the graphical application for installation
but the default tab in the how-to guides is for the Windows registry.

Minor changes:

- UI improvements: use of tabbed interfaces for user choice between
Windows app and Windows registry
- Internal references: updated internal Sphinx references for many
sections
- Rewording/fixes: minor changes throughout
- Updated images: throughout


UDENG-3595

docs/.custom_wordlist.txt

@@ -62,6 +62,7 @@ url
 zshrc
 ESM
 Ok
+scalability
 
 # Registry keys and types
 DWORD

docs/dev/howto/02-install.md

@@ -23,7 +23,7 @@ This guide will show you how to install UP4W for local development and testing.
 
 Notice that, for the step above, there is also an alternative version of the MSIX bundle enabled for end-to-end testing. Most likely, that's not what you want to download.
 
-(dev::install::agent)=
+(dev::install-agent)=
 ## 2. Install the Windows Agent
 
 This is the Windows-side agent that manages the distros.

docs/dev/howto/reset-factory.md

@@ -23,5 +23,5 @@ You can reset Ubuntu Pro for WSL to factory settings following these steps:
    4. Find the `UbuntuPro` key on the left
    5. Right-click on it
    6. Click delete
-5. Install the Windows Agent package again (see the section on [how to install](dev::install::agent)). You do not need to re-install the WSL-Pro-Service.
+5. Install the Windows Agent package again (see the section on [how to install](dev::install-agent)). You do not need to re-install the WSL-Pro-Service.
 6. You're done. Next time you start the GUI it'll be like a fresh install.

docs/howto/backup-and-restore.md

@@ -0,0 +1,98 @@
+# Back up, restore and duplicate Ubuntu WSL instances
+
+## Motivation
+
+You may need to backup one of your Ubuntu WSL instances, if you want to:
+
+- Perform a clean installation without losing data
+- Create a snapshot before experimenting with your instance
+- Share a pre-configured instance between machines
+- Duplicate an instance so it can be run and configured independently
+
+(howto::backup)=
+## Backing up
+
+```{note}
+For simplicity, PowerShell commands in this section will all be run from the home
+directory of the user `me`.
+```
+
+To backup an Ubuntu-24.04 instance first make a `backup` folder in your home directory:
+
+```text
+PS C:\Users\me> mkdir backup
+```
+
+You then need to create a compressed version of the Ubuntu instance in that backup directory:
+
+```text
+PS C:\Users\me> wsl --export Ubuntu-24.04 .\backup\Ubuntu-24.04.tar.gz
+```
+
+(howto::removal)=
+## Removal and deletion
+
+Once you have created a backup of your Ubuntu distro it is safe to
+remove it from WSL and delete all associated data.
+
+This can be achieved with the following command:
+
+```text
+PS C:\Users\me> wsl --unregister Ubuntu-24.04
+```
+
+(howto::restoring)=
+## Restoring
+
+If you want to restore the Ubuntu-24.04 instance that you have previously backed up run:
+
+```text
+PS C:\Users\me> wsl --import Ubuntu-24.04 .\backup\Ubuntu2404\ .\backup\Ubuntu-24.04.tar.gz
+```
+
+This will import your previous data and if you run `ubuntu2404.exe` an Ubuntu WSL instance
+should be restored with your previous configuration intact.
+
+To login as a user `k`, created with the original instance, run: 
+
+```text
+PS C:\Users\me> wsl -d Ubuntu-24.04 -u k
+```
+
+Alternatively, add the following to `/etc/wsl.conf` in the instance:
+
+```text
+[user]
+default=k
+```
+
+Without specifying a user you will be logged in as the root user.
+
+(howto::duplication)=
+## Duplication
+
+It is also possible to create multiple instances from a base instance.
+Below the restore process is repeated but the new instances are assigned
+different names than the original backup:
+
+```text
+PS C:\Users\me> wsl --import ubuntu2404b .\backup\Ubuntu2404b\ .\backup\Ubuntu-24.04.tar.gz
+PS C:\Users\me> wsl --import ubuntu2404c .\backup\Ubuntu2404c\ .\backup\Ubuntu-24.04.tar.gz
+```
+
+This will create two additional instances of Ubuntu 24.04 that can be launched and configured independently.
+
+In PowerShell, running `wsl -l -v` will output the new instances in your list of installed distributions:
+
+```text
+NAME            STATE         VERSION
+Ubuntu-24.04    Stopped       2
+ubuntu2404b     Stopped       2
+ubuntu2404c     Stopped       2
+```
+
+To launch the first derived instance and login as the user `k` run:
+
+```text
+PS C:\Users\me> wsl -d ubuntu2404b -u k
+```

docs/howto/index.md

@@ -7,6 +7,10 @@ These how-to guides cover key operations and processes in UP4W.
 ```{toctree}
 :titlesonly:
 
-Install and configure UP4W <set-up-up4w>
-Install Landscape server in WSL <set-up-landscape-server-in-wsl>
+Install UP4W and add a Pro token <set-up-up4w>
+Verify Pro subscription and attachment <verify-subscribe-attach>
+Back up and restore Ubuntu WSL instances <backup-and-restore>
+Uninstalling UP4W, Ubuntu WSL apps and WSL <uninstalling>
+Configure the Landscape client with UP4W  <set-up-landscape-client>
+Set up a Landscape server within WSL <set-up-landscape-server-in-wsl>
 ```

docs/howto/set-up-landscape-client.md

@@ -0,0 +1,109 @@
+# Configure the Landscape client with UP4W
+
+(howto::config-landscape)=
+## Choose a configuration method
+
+The Landscape client can be configured in two ways:
+
+- Windows registry: easier to automate and deploy at scale 
+- Graphical Windows application: convenient option for individual users
+
+```{tip}
+Landscape configuration in the UP4W application must currently be enabled by setting
+`ShowLandscapeConfig:DWORD=1` at `HKCU:/Software/Canonical/UbuntuPro` in the Windows
+registry.
+```
+
+Click the appropriate tab to read more.
+
+````{tabs}
+
+```{group-tab} Windows registry
+
+## Access the registry
+
+First, ensure that UP4W has run at least once after installation.
+This ensures that the key and values necessary for configuration will be set up
+in the registry.
+
+Advanced users of the registry can find relevant information in the
+[Microsoft documentation](https://learn.microsoft.com/en-us/troubleshoot/windows-server/performance/windows-registry-advanced-users)
+about alternative methods for modifying the registry data.
+
+To open the registry type `Win+R` and enter `regedit`:
+
+![Windows where regedit command is run.](./assets/regedit.png) 
+
+## Configure Landscape in the registry
+
+If you are using Landscape you can input your configuration in `LandscapeConfig > Modify > Write the Landscape config`:
+
+![Windows registry with child window showing Landscape configuration.](./assets/registry-child-window-config.png) 
+
+Refer to the section on [Landscape client configuration](howto::config-landscape-client) for an example.
+
+After you have populated the configuration with data you should be ready to create and manage 
+automatically Pro-attaching WSL instances through Landscape:
+
+![Windows registry showing completed Ubuntu Pro for WSL configuration.](./assets/registry-complete.png) 
+
+```
+
+```{group-tab} Graphical Windows application
+In the UP4W app navigate to the Landscape configuration screen:
+
+![UP4W GUI main screen](../assets/landscape-config-ui.png)
+
+Choose your preferred configuration option and enter the required details.
+
+The "Advanced Configuration" option requires you to specify a `landscape.conf`.
+Refer to the section on [Landscape client configuration](howto::config-landscape-client) for an example.
+
+When you continue a status screen will appear confirming that configuration is complete:
+
+![Configuration is complete](../assets/status-complete.png)
+
+### Note on SSL public key
+
+If the machine running the server is not trusted on your network you may need to
+explicitly reference a path to the SSL public key on a Windows host machine.
+
+For example, if you followed the [Landscape Quickstart](https://ubuntu.com/landscape/docs/quickstart-deployment)
+installation, the auto-generated self-signed certificate can be found at `/etc/ssl/certs/landscape_server.pem`.
+
+This can be copied to a Windows machine:
+
+  C:\Users\\<YOUR_WINDOWS_USER_NAME>\landscape_server.pem
+
+The path can then be referenced during Landscape configuration in the UP4W Windows app.
+If necessary, the SSL public key can be added after the Windows host has first
+been registered in Landscape.
+
+```
+
+````
+
+(howto::config-landscape-client)=
+## Configuring the landscape client
+
+Both the `LandscapeConfig` data in the Windows registry and the Advanced Configuration
+option in the graphical Windows application can be configured as follows:
+
+
+```ini
+[host]
+url = landscape-server.domain.com:6554
+
+[client]
+url = https://landscape-server.domain.com/message-system
+ping_url  = http://landscape-server.domain.com/ping
+account_name = standalone
+log_level = debug
+ssl_public_key = C:\Users\user\Downloads\landscape_server.pem
+```
+
+```{warning}
+The `ping_url` must be a `http` address. A `https` address will not work.
+```
+
+A more comprehensive example of the configuration options is provided [here](https://github.com/canonical/landscape-client/blob/main/example.conf).

docs/howto/set-up-landscape-server-in-wsl.md

@@ -1,15 +1,16 @@
-# How to install Landscape server in a WSL instance
+# Install Landscape server in a WSL instance
 
 ## Motivation
 
 While a Landscape server typically runs on external computers, it can also be
 set up on a WSL instance on a Windows machine.
 
 This is especially useful if you want to test UP4W on a single Windows device.
-For example, the [tutorial](../tutorial/index) can be completed with Landscape
-server running in a Ubuntu WSL instance. The Landscape server can then be used
+For example, the [tutorial](../tutorial/index) can be completed with a Landscape
+server running in an Ubuntu WSL instance. The Landscape server can then be used
 to manage other WSL instances running UP4W and the Landscape client.
 
+(howto::config-landscape-server)=
 ## Guide
 
 In PowerShell, `shutdown` WSL then install the Ubuntu 24.04 LTS instance with