docs: UX fixes for RTD docs

CONTRIBUTING.md

@@ -1,5 +1,5 @@
 <!-- Include start contributing intro -->
-# Contributing to Authd
+# Contributing to authd
 
 A big welcome and thank you for considering making a contribution to authd and Ubuntu! It’s people like you that help make these products a reality for users in our community.
 

docs/conf.py

@@ -23,7 +23,7 @@
 #
 # TODO: Update with the official name of your project or product
 
-project = "Authd"
+project = "authd"
 author = "Canonical Ltd."
 
 
@@ -134,6 +134,9 @@
     # NOTE: If set, links for viewing the documentation source files
     #       and creating GitHub issues are added at the bottom of each page.
     "github_url": "https://github.com/ubuntu/authd",
+    # 
+    # Add a feedback button
+    'github_issues': 'enabled',
     # Docs branch in the repo; used in links for viewing the source files
     #
     # TODO: To customise the branch, uncomment and update as needed.

docs/explanation/authd-architecture.md

@@ -1,17 +1,17 @@
-# Authd architecture
+# authd architecture
 
-Authd can help organisations ensure secure identity and access management by enabling seamless cloud-based authentication of Ubuntu machines.
+authd can help organisations ensure secure identity and access management by enabling seamless cloud-based authentication of Ubuntu machines.
 Here we explain the architecture of authd and some of its design decisions.
 Links are provided at the end to support further reading.
 
 ## Architecture components
 
-Authd acts as an interface between the host system and external identity providers. 
+authd acts as an interface between the host system and external identity providers. 
 Remote information is cached when authenticating with authd, which improves performance while also facilitating offline access.
 
 The diagram below illustrates the components of authd and their communication methods:
 
-![isoflow-export-2024-08-30T13_44_31 725Z](../assets/authd-architecture.png)
+![Isometric architecture diagram of authd.](../assets/authd-architecture.png)
 
 The architecture of authd consists of the following components:
 

docs/explanation/index.md

@@ -5,5 +5,5 @@
 ```{toctree}
 :titlesonly:
 
-Authd architecture <authd-architecture>
+authd architecture <authd-architecture>
 ```

docs/howto/configure-authd.md

@@ -17,19 +17,19 @@ Register a new application in the Microsoft Azure portal. Once the application i
 
 To register a new application, in Entra, select the menu `Identity > Applications > App registration`
 
-![image](../assets/app-registration.png)
+![Menu showing selection of App registrations under Applications.](../assets/app-registration.png)
 
 Then `New registration`
 
-![image](../assets/new-registration.png)
+![User interface showing selection of New registration in App registrations.](../assets/new-registration.png)
 
 And configure it as follows:
 
-![image](../assets/configure-registration.png)
+![Configuration screen for the new registration.](../assets/configure-registration.png)
 
 Under `Manage`, in the `API permissions` menu, set the following Microsoft Graph permissions:
 
-![image](../assets/graph-permissions.png)
+![Configuration screen for Microsoft Graph permissions.](../assets/graph-permissions.png)
 
 Ensure the API permission type is set to **Delegated** for each permission.
 

docs/howto/index.md

@@ -9,5 +9,5 @@ Install authd <install-authd>
 Configure authd <configure-authd>
 Login with GDM <login-gdm>
 Login with SSH <login-ssh>
-Contributing to Authd <contributing>
+Contributing to authd <contributing>
 ```

docs/howto/install-authd.md

@@ -4,7 +4,7 @@ This project consists of two components:
 * authd: The authentication daemon responsible for managing access to the authentication mechanism.
 * an identity broker: The services that handle the interface with an identity provider. There can be several identity brokers installed and enabled on the system.
 
-Authd is delivered as a Debian package.
+authd is delivered as a Debian package.
 
 ## System requirements
 

docs/howto/login-gdm.md

@@ -10,23 +10,23 @@ Type your MS Entra ID user name. The format is ```[email protected]```
 
 Select the broker `Microsoft Entra ID`
 
-![image](../assets/gdm-select-broker.png)
+![Login screen showing selection of broker.](../assets/gdm-select-broker.png)
 
 If MFA is enabled, a QR code and a login code are displayed.
 
-![image](../assets/gdm-qr.png)
+![Display of QR code, login code and button to Request new login code.](../assets/gdm-qr.png)
 
 From a second device, flash the QR code or type the URL in a web browser, then follow the authentication process from your provider.
 
 Upon successful authentication, the user is prompted to enter a local password. This password can be used for offline authentication.
 
-![image](../assets/gdm-pass.png)
+![Prompt to create local password on successful authentication.](../assets/gdm-pass.png)
 
 ## Groups management
 
-In our example the user `authd test` is a member of the following Azure groups:
+In our example the user `authd test` is a member of the Azure groups `Azure_OIDC_Test` and `linux-sudo`:
 
-![image](../assets/gdm-groups.png)
+![Azure portal interface showing the Azure groups.](../assets/gdm-groups.png)
 
 This translates to the following unix groups on the local machine:
 

docs/howto/login-ssh.md

@@ -57,4 +57,4 @@ For instance:
 ssh [email protected]@remote.host
 ```
 
-![image](../assets/ssh-qr.png)
+![Terminal interface showing option to authentice by login code or QR scan when user tries to ssh into server](../assets/ssh-qr.png)

docs/index.md

@@ -1,10 +1,10 @@
-# Authd
+# authd
 
-Authd is a versatile authentication service for Ubuntu, designed to seamlessly integrate with cloud identity providers like OpenID Connect and Entra ID. It offers a secure interface for system authentication, enabling cloud-based identity management. It can be used to support logins through both GDM and SSH.
+authd is a versatile authentication service for Ubuntu, designed to seamlessly integrate with cloud identity providers like OpenID Connect and Entra ID. It offers a secure interface for system authentication, enabling cloud-based identity management. It can be used to support logins through both GDM and SSH.
 
-Authd features a modular structure, facilitating straightforward integration with different cloud services. This design aids in maintaining strong security and effective user authentication. It's well-suited for handling access to cloud identities, offering a balance of security and ease of use.
+authd features a modular structure, facilitating straightforward integration with different cloud services. This design aids in maintaining strong security and effective user authentication. It's well-suited for handling access to cloud identities, offering a balance of security and ease of use.
 
-Authd uses brokers to interface with cloud identity providers through a [DBus API](https://github.com/ubuntu/authd/blob/HEAD/examplebroker/com.ubuntu.auth.ExampleBroker.xml). Currently only [MS Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/whatis) is supported. For development purposes, Authd also provides an example broker to help you develop your own.
+authd uses brokers to interface with cloud identity providers through a [DBus API](https://github.com/ubuntu/authd/blob/HEAD/examplebroker/com.ubuntu.auth.ExampleBroker.xml). Currently only [MS Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/whatis) is supported. For development purposes, authd also provides an example broker to help you develop your own.
 
 The [MS Entra ID broker](https://github.com/ubuntu/oidc-broker) allows you to authenticate against MS Entra ID using MFA and the device authentication flow.
 
@@ -15,7 +15,9 @@ The [MS Entra ID broker](https://github.com/ubuntu/oidc-broker) allows you to au
 <!-- NOTE: changed grid layout as there is only three cards -->
 ````{grid} 1 1 1 1
 
-```{grid-item-card} [How-to guides](index)
+```{grid-item-card} [How-to guides](howto/index)
+:link: howto/index
+:link-type: doc
 
 **Step-by-step guides** covering key operations and common tasks
 ```
@@ -25,12 +27,16 @@ The [MS Entra ID broker](https://github.com/ubuntu/oidc-broker) allows you to au
 ````{grid} 1 1 2 2
 :reverse:
 
-```{grid-item-card} [Reference](index)
+```{grid-item-card} [Reference](reference/index)
+:link: reference/index
+:link-type: doc
 
 **Technical information** on troubleshooting authd
 ```
 
-```{grid-item-card} [Explanations](index)
+```{grid-item-card} [Explanation](explanation/index)
+:link: explanation/index
+:link-type: doc
 
 **Discussion** of product architecture
 ```
@@ -41,18 +47,18 @@ The [MS Entra ID broker](https://github.com/ubuntu/oidc-broker) allows you to au
 
 ## Project and community
 
-Authd is a member of the Ubuntu family. It’s an open source project that warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback.
+authd is a member of the Ubuntu family. It’s an open source project that warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback.
 
 * [Code of conduct](https://ubuntu.com/community/ethos/code-of-conduct)
 * [Contribute](/howto/contributing)
 
-Thinking about using Authd for your next project? Get in touch!
+Thinking about using authd for your next project? Get in touch!
 
 ```{toctree}
 :hidden:
 :maxdepth: 2
 
-Authd <self>
+authd <self>
 How-to guides </howto/index>
 Reference </reference/index>
 Explanation </explanation/index>