docs: add landing pages and start content restructure

docs/dev/howto/index.md → docs/howto/index-contributing.md

@@ -1,15 +1,17 @@
-(dev-howtos)=
+(index-contributing)=
 
-# How-to guides
+# Contributing to UP4W
 
-These how-to guides cover key operations and processes in Ubuntu Pro for WSL.
+These how-to guides help you complete tasks when developing for UP4W.
 
 ```{toctree}
 :titlesonly:
+:maxdepth: 1
 
 Install UP4W <02-install>
 Restart UP4W <03-restart>
 Access UP4W logs <06-access-the-logs>
 Enable opt-in features <07-toggle-features>
 Reset UP4W <reset-factory>
 ```
+

docs/howto/index-remote-deployment.md

@@ -0,0 +1,15 @@
+(index-remote-deployment)=
+
+# Remote deployment
+
+These how-to guides help you deploy and manage WSL instances with UP4W.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+Configure the Landscape client with UP4W  <set-up-landscape-client>
+Create WSL instances on multiple Windows machines with the Landscape API <custom-rootfs-multiple-targets>
+Enforce the UP4W background agent startup remotely using the Windows Registry <enforce-agent-startup-remotely-registry>
+Start the UP4W background agent remotely <start-agent-remotely>
+```

docs/howto/index-setup.md

@@ -0,0 +1,16 @@
+(index-setup)=
+
+# UP4W setup
+
+These how-to guides show you how to set up UP4W.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+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>
+```
+

docs/howto/index.md

@@ -2,18 +2,34 @@
 
 # How-to guides
 
-These how-to guides cover key operations and processes in UP4W.
+The guides in this section will help you quickly
+complete specific tasks with UP4W.
+
+Install and set up of UP4W with the aid of these guides:
+
+```{toctree}
+:titlesonly:
+
+index-setup
+
+```
+
+When remotely deploying and managing Ubuntu WSL instances, the following guides
+are helpful:
 
 ```{toctree}
 :titlesonly:
 
-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>
-Create WSL instances on multiple Windows machines with the Landscape API <custom-rootfs-multiple-targets>
-Enforce the UP4W background agent startup remotely using the Windows Registry <enforce-agent-startup-remotely-registry>
-Start the UP4W background agent remotely <start-agent-remotely>
+index-remote-deployment
+
+```
+
+If you are interested in contributing to UP4W as a developer, consult the
+guides below:
+
+```{toctree}
+:titlesonly:
+
+index-contributing
+
 ```

docs/index.md

@@ -15,33 +15,34 @@ Read our [getting started tutorial](tutorial/getting-started) to begin.
 
 ## In this documentation
 
-````{grid} 1 1 2 2
+````{grid} 1 1 1 1
 
 ```{grid-item-card} [Tutorials](tutorial/index)
+:link: tutorial/index
+:link-type: doc
 
 **Start here** with hands-on tutorials for new users, guiding you through your first-steps
 ```
 
+````
+
+````{grid} 1 1 2 2
+
 ```{grid-item-card} [How-to guides](howto/index)
+:link: howto/index
+:link-type: doc
 
 **Follow step-by-step** instructions for key operations and common tasks
 ```
 
-````
-
-````{grid} 1 1 2 2
-:reverse:
 
 ```{grid-item-card} [Reference](reference/index)
+:link: reference/index
+:link-type: doc
 
 **Read technical descriptions** of important factual information relating to UP4W
 ```
 
-```{grid-item-card} [UP4W Dev](dev/index)
-
-**Review guides and reference material** aimed at contributors
-```
-
 ````
 
 ## Project and community
@@ -58,5 +59,4 @@ UP4W <self>
 Tutorial </tutorial/index>
 How-to guides </howto/index>
 Reference </reference/index>
-UP4W Dev </dev/index>
 ```

docs/reference/index.md

@@ -1,21 +1,32 @@
+(reference)=
+
 # Reference
 
-Our reference section contains more detailed information about the several
-pieces that make up the Ubuntu Pro for WSL tool and the value it provides.
+This section contains concise references relating to how UP4W is designed,
+configured and developed:
+
+Descriptions of key UP4W components can be found here:
+
+```{toctree}
+:titlesonly:
+
+index_up4w_components
+```
+
+Details on firewall configuration, Landscape setup and using the Windows
+registry can be found here:
+
+```{toctree}
+:titlesonly:
+
+index_system_configuration
+```
+
+Information for contributors that is helpful for debugging code and ensuring
+code quality is outlined below:
 
 ```{toctree}
 :titlesonly:
 
-firewall_requirements
-landscape
-landscape_client
-ubuntu_pro
-ubuntu_pro_client
-ubuntu_wsl
-UP4W <up4w>
-UP4W - GUI <up4w-gui>
-up4w-windows_agent
-up4w-wsl_pro_service
-windows_registry
-WSL <wsl>
+index_up4w_development
 ```

docs/reference/index_system_configuration.md

@@ -0,0 +1,15 @@
+(index-system-configuration)=
+
+# System configuration
+
+When configuring firewall settings, Landscape clients or the Windows registry,
+the following references may be useful:
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+firewall_requirements
+landscape_config
+windows_registry
+```

docs/reference/index_up4w_components.md

@@ -0,0 +1,41 @@
+(index-system-components)=
+
+# UP4W components
+
+Some Ubuntu Pro for WSL (UP4W) components run on the Windows host:
+
+- The [UP4W Windows Agent](ref::up4w-windows-agent) that provides automation
+services.
+- The [UP4W GUI](ref::up4w-gui) for end users to manage their Ubuntu Pro
+subscription and Landscape configuration.
+
+UP4W also requires a component running inside each of the WSL distros:
+
+- The [WSL Pro Service](ref::up4w-wsl-pro-service) communicates with the
+Windows Agent to provide automation services.
+
+Find additional detail on the individual components of UP4W below:
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+up4w-windows_agent
+up4w-gui
+up4w-wsl_pro_service
+landscape_client
+ubuntu_pro_client
+```
+
+```{admonition} Supporting technologies
+Windows Subsystem for Linux (**WSL**) makes it possible to run Linux
+distributions on Windows. UP4W runs on Windows hosts to manage **Ubuntu WSL**
+instances, automatically attaching them to an **Ubuntu Pro** subscription and
+enrolling them into **Landscape**. For more information on these technologies,
+you can refer to their official documentation:
+
+* [Official Ubuntu WSL documentation](https://documentation.ubuntu.com/wsl/en/latest/)
+* [Official Microsoft WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/)
+* [Official Landscape documentation](https://ubuntu.com/landscape/docs)
+
+```

docs/dev/reference/index.md → docs/reference/index_up4w_development.md

@@ -1,13 +1,13 @@
-(reference)=
+(debugging-and-testing)=
 
-# Reference
+# Debugging and testing
 
-The reference material in this section provides technical descriptions of Ubuntu Pro for WSL.
+The reference material in this section is helpful for contributors when debugging the application
+and contributing code.
 
 ```{toctree}
 :titlesonly:
 
-
 Windows Agent CLI <07-windows-agent-command-line-reference>
 WSL Pro Service CLI <08-wsl-pro-service-command-line-reference>
 QA process <09-qa-process-reference>