docs: add landing pages and start content restructure (#981)

This marks the start of a content restructure for the UP4W documentation. The **major** changes include: * **Landing pages** are added for each Diataxis section with text guiding the user through the contents, with the embedded TOC divided into sub-sections. Landing pages will need to be revisited when/if new content is added. * **Sub-sections** are added where individual Ditaxis sections contain multiple doc pages spanning different topics * **Developer documentation** is incorporated directly into the main documentation (`how-to guides>contributing to UP4W` and `reference>debugging and testing`) * **Generic, small pages relating to other software** (WSL, Landscape, Ubuntu WSL) are removed and replaced with external links to the relevant documentation (see "supporting technologies" in `reference>UP4W components`) * **Deletion** of the guide outlining how to set up landscape server on WSL; this does not serve an obvious user need currently and does not have an suitable place in the documentation) Some planned changes are **out of scope** for this PR: * A Diataxis Explanation section will be added in a future PR to accommodate content relating to -- at a minimum -- UP4W architecture. At that point, material in `reference>UP4W components` may be consolidated further. * Some content, including the guide `back up and restore ubuntu WSL instances` may be a better fit for the Ubuntu WSL docs and will be considered as part of separate work aimed at restructuring those docs. * The styling of the landing pages could be improved. The top-level bullet for each sub-section is not needed but removing this requires changing how the toc-trees are included on each page. When these are removed, headers will be added to more clearly distinguish the sections. During the restructure there were some minor changes to wording and links. UDENG-5304
canonical · Dec 3, 2024 · 35ca57a · 35ca57a
2 parents 8404d08 + bccc9c4
commit 35ca57a
Show file tree

Hide file tree

Showing 36 changed files with 209 additions and 243 deletions.
diff --git a/docs/dev/index.md b/docs/dev/index.md
diff --git a/docs/dev/howto/02-install.md → docs/howto/02-install.md b/docs/dev/howto/02-install.md → docs/howto/02-install.md
diff --git a/docs/dev/howto/03-restart.md → docs/howto/03-restart.md b/docs/dev/howto/03-restart.md → docs/howto/03-restart.md
diff --git a/docs/dev/howto/06-access-the-logs.md → docs/howto/06-access-the-logs.md b/docs/dev/howto/06-access-the-logs.md → docs/howto/06-access-the-logs.md
diff --git a/docs/dev/howto/07-toggle-features.md → docs/howto/07-toggle-features.md b/docs/dev/howto/07-toggle-features.md → docs/howto/07-toggle-features.md
diff --git a/docs/dev/howto/index.md → docs/howto/index-contributing.md b/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>
 ```
+
diff --git a/docs/howto/index-remote-deployment.md b/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>
+```
diff --git a/docs/howto/index-setup.md b/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>
+```
+
diff --git a/docs/howto/index.md b/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
+
 ```
diff --git a/docs/dev/howto/reset-factory.md → docs/howto/reset-factory.md b/docs/dev/howto/reset-factory.md → docs/howto/reset-factory.md
diff --git a/docs/howto/set-up-landscape-server-in-wsl.md b/docs/howto/set-up-landscape-server-in-wsl.md
diff --git a/docs/index.md b/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>
 ```
diff --git a/...7-windows-agent-command-line-reference.md → ...7-windows-agent-command-line-reference.md b/...7-windows-agent-command-line-reference.md → ...7-windows-agent-command-line-reference.md
diff --git a/...wsl-pro-service-command-line-reference.md → ...wsl-pro-service-command-line-reference.md b/...wsl-pro-service-command-line-reference.md → ...wsl-pro-service-command-line-reference.md
diff --git a/.../dev/reference/09-qa-process-reference.md → docs/reference/09-qa-process-reference.md b/.../dev/reference/09-qa-process-reference.md → docs/reference/09-qa-process-reference.md
diff --git a/docs/reference/assets/Landscape.drawio.svg b/docs/reference/assets/Landscape.drawio.svg
diff --git a/docs/reference/index.md b/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
 ```
diff --git a/docs/reference/index_system_configuration.md b/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
+```
diff --git a/docs/reference/index_up4w_components.md b/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)
+
+```
diff --git a/docs/dev/reference/index.md → docs/reference/index_up4w_development.md b/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>