docs: homepage refresh (#1207)

Various changes to improve the user experience when finding and visiting
the docs for the first time:

* Homepage: decreased repetition of content; made less Desktop-specific;
improved flow and organisation; linked to specific content from Diataxis
cards; converted grid items to cards for improved padding between items
* Made page titles less generic: some pages were made more
discoverable/searchable by giving them more descriptive titles
* Fixed title: title(s) at top of the documentation should refer to the
name used to identify the feature -- ADSys -- rather than its role or
function, which is already specified in the main text
* Edit button: added an edit button at the top of the page to make it
more obvious to users wishing to make minor contributions
* Misc: some fixes to links


UDENG-6060

docs/custom_conf.py

@@ -19,7 +19,7 @@
 ############################################################
 
 # Product name
-project = "Active Directory GPO client"
+project = "ADSys"
 author = "Canonical Group Ltd"
 
 # The title you want to display for the documentation in the sidebar.
@@ -48,6 +48,13 @@
 #   -H 'Accept: application/vnd.github.v3.raw' \
 #   https://api.github.com/repos/canonical/<REPO> | jq '.created_at'
 
+# This adds an edit button to the top of each page
+html_theme_options = {
+    "source_repository": "https://github.com/ubuntu/adsys/",
+    "source_branch": "main",
+    "source_directory": "docs/",
+}
+
 copyright = "%s CC-BY-SA, %s" % (datetime.date.today().year, author)
 
 ## Open Graph configuration - defines what is displayed as a link preview

docs/explanation/index.md

@@ -26,6 +26,6 @@ scripts
 AppArmor Profiles <apparmor>
 network-shares
 proxy
-Certificates Auto-Enrolment <certificates>
+Certificates Auto-Enrollment <certificates>
 Security Policy <security-policy>
 ```

docs/how-to/join-ad-installation.md

@@ -1,8 +1,8 @@
-# How to join an Active Directory domain during installation
+# How to join Ubuntu Desktop to an Active Directory domain during installation
 
 In order to use Group Policies on an Ubuntu client, the first thing to do is, of course, to join the computer to an Active Directory domain.
 
-A machine can join an AD domain at installation time with the Ubuntu Desktop installer, or after installation, by manually setting up the connection to AD.
+A machine can join an AD domain at installation time with the Ubuntu Desktop installer, or after installation, by [manually setting up the connection to AD](join-ad-manually.md).
 
 ## Join at installation time
 

docs/how-to/join-ad-manually.md

@@ -1,4 +1,4 @@
-# How to join an Active Directory domain manually
+# How to manually join Ubuntu clients to an Active Directory domain
 
 ADSys supports two Active Directory backends:
 

docs/how-to/set-up-ad.md

@@ -1,4 +1,4 @@
-# How to set up the Active Directory Server
+# How to set up the Active Directory server for Ubuntu clients
 
 Active Directory needs policy files (**.admx** and **.adml**) to know which settings can be changed on given clients and actions to be performed on users of the domain.
 

docs/how-to/set-up-adsys.md

@@ -1,4 +1,4 @@
-# How to set-up ADSys
+# How to set up ADSys
 
 **ADSys** is not currently installed by default on Ubuntu desktop. This must be done manually by the local administrator of the machine.
 

docs/index.md

@@ -2,11 +2,11 @@
 
 ADSys is the Active Directory Group Policy client for Ubuntu.
 
-ADSys enables system administrators to manage Ubuntu Desktop clients centrally via Microsoft Active Directory. It includes ADMX and ADML templates and allows policies to be applied at boot and login, then refreshed periodically.
+ADSys enables management of Ubuntu Desktop and Server clients using Microsoft Active Directory. It integrates with services like SSSD or Winbind, which handle user access and authentication, providing extended functionality for managing and controlling Ubuntu clients.
 
-It simplifies the task of configuring Ubuntu systems in a Microsoft Active Directory environment. However, it doesn't handle user authentication or initial security policy, which are managed by SSSD/Winbind and PAM.
+With ADSys, policies can be applied to Ubuntu clients at boot and login, privileges can be granted and revoked, and remote script execution can be automated. Administrative templates (ADMX and ADML) are provided for all supported versions of Ubuntu.
 
-ADSys is valuable for system administrators who wish to manage Ubuntu Desktop clients in a centralized manner through Microsoft Active Directory.
+System administrators can use ADSys to apply their skills and tools for managing Windows machines using Microsoft Active Directory to the management of Ubuntu machines.
 
 ```{toctree}
 :hidden:
@@ -18,34 +18,48 @@ explanation/index
 
 ## In this documentation
 
+
 ````{grid} 1 1 2 2
 
-```{grid-item}
+```{grid-item-card}
 ### [Tutorials](tutorial/index)
 
-**Learn about ADSys features** with hands-on tutorials
+**Learn** to use an ADSys feature:
+
+* [Certificate auto-enrollment with ADSys](/tutorial/certificates-auto-enrollment)
+
 ```
 
-```{grid-item}
+```{grid-item-card}
 ### [How-to guides](how-to/index)
 
-**Step-by-step guides** covering key operations and common tasks
+**Follow guides** for specific tasks, like:
+
+* [Joining to AD on Ubuntu Desktop install](/how-to/join-ad-manually)
+* [Setting up ADSys on Ubuntu Desktop](./how-to/set-up-adsys.md)
 ```
 
 ````
 
 ````{grid} 1 1 2 2
 
-```{grid-item}
+```{grid-item-card}
 ### [Explanation](explanation/index)
 
-**Discussion and clarification** of key topics
+**Understand** topics including:
+
+* [The architecture of ADSys](/explanation/adsys-ref-arch)
+* [Client configuration using Dconf](./explanation/dconf)
 ```
 
-```{grid-item}
+```{grid-item-card}
 ### [Reference](reference/index)
 
-**Technical information** - specifications, APIs, architecture
+**Find specific information**, such as:
+
+* [Policies supported by ADSys](/reference/policies/index)
+* [The ADSys daemon](/reference/adsysd-cli)
+
 ```
 
 ````