several improvements to documentation

docs/architecture.rst

 Architecture
 ============
 
-The single sign on system consists of a few components:
+The single sign-on system consists of a few components:
 
-1. The *Oauth2* and *OpenID Connect (OIDC) provider*, `Hydra`_
+1. The *OAuth 2* and *OpenID Connect (OIDC) provider*, `Hydra`_
 2. The *Identity provider*, `Kratos`_
-3. The `Login application`_ which serves as a login panel, consent application
-   and a settings screen for the Kratos settings (mostly used for password
-   reset).
+3. The Login application which serves as a login panel, consent application and
+   a settings screen for the Kratos settings. `The login application code can be
+   found here
+   <https://open.greenhost.net/stackspin/single-sign-on/-/tree/main/login>`__
 
 .. _Hydra: https://www.ory.sh/hydra/docs/
 .. _Kratos: https://www.ory.sh/kratos/docs/
-.. _Login application: https://open.greenhost.net/stackspin/single-sign-on/-/tree/main/login
 
 Overview
 --------
 
-The single sign on application as a whole stores your users and helps them
-authenticate to applications. Its users are stored inside Kratos's database.
-Kratos also serves an API that helps us generate interfaces for many
-user-related tasks, such as:
+The single sign-on system is a combination of applications that serve as a
+central user database and authenticates them to other applications. Users are
+stored inside Kratos's database.  Kratos also serves an API that helps us
+generate interfaces for many user-related tasks, such as:
 
 1. Setting your name and username
 2. The whole password reset flow
@@ -27,7 +27,7 @@ user-related tasks, such as:
 4. 2FA (not implemented in the login application yet)
 
 The Login application is mostly a front-end that uses the Kratos API to generate
-the views for logging in, resetting the password and setting some user data.
+interfaces for logging in, resetting the password and setting some user data.
 
 
 Flows
@@ -76,8 +76,10 @@ User settings
 
 Although users can change their settings through the `Dashboard application
 <https://open.greenhost.net/stackspin/dashboard>`__, the login application also
-has a version of the `user-settings Kratos flow
+implements the `user-settings Kratos flow
 <https://www.ory.sh/kratos/docs/next/self-service/flows/user-settings/>`__.
+Users that receive a password recovery link use this flow to reset their
+passwords. It also allows them to change their username and full name.
 
 Authentication
 ~~~~~~~~~~~~~~
@@ -88,7 +90,7 @@ documentation <https://www.ory.sh/docs/hydra/concepts/login>`__
 .. mermaid::
 
    sequenceDiagram
-      OAuth2 Client->>Ory Hydra: Initiates OAuth2 Authorize Code or Implicit Flow
+      OAuth 2 Client->>Ory Hydra: Initiates OAuth 2 Authorize Code or Implicit Flow
       Ory Hydra-->>Ory Hydra: No end user session available (not authenticated)
       opt Login Application as Login Provider
         Ory Hydra->>Login Application: Redirects end user with login challenge
@@ -106,7 +108,7 @@ documentation <https://www.ory.sh/docs/hydra/concepts/login>`__
         Login Application->>Ory Hydra: Redirects to redirect url with consent verifier
       end
       Ory Hydra-->>Ory Hydra: Verifies grant
-      Ory Hydra->>OAuth2 Client: Transmits authorization code/token`
+      Ory Hydra->>OAuth 2 Client: Transmits authorization code/token`
 
 Configuring OIDC clients
 ------------------------

docs/conf.py

@@ -65,3 +65,13 @@ html_css_files = ['custom.css']
 # Readthedocs.io needs us to tell it what the index file is. This defaults to
 # 'contents'
 master_doc = 'index'
+
+# https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html
+#
+# Suppress autosectionlabel extension warnings about duplicate labels, i.e.
+#
+#   docs/usage.rst:105: WARNING: duplicate label wordpress, other instance in docs/testing.rst
+#
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 5

docs/helmchart.md

@@ -35,7 +35,7 @@ This table lists the variables you are most likely to change. Take a look at the
 
 | Parameter                            | Description                                             | Default                                 |
 |--------------------------------------|---------------------------------------------------------|-----------------------------------------|
-| `singleSignOnHost`                   | **FQDN of the openID Connect / oAuth2 server**          | **sso.stackspin.example.net**           |
+| `singleSignOnHost`                   | **FQDN of the openID Connect / OAuth 2 server**          | **sso.stackspin.example.net**           |
 | `login.image.repository`             | Name of image repository to be used for login provider  | open.greenhost.net:4567/stackspin/single-sign-on/login |
 | `login.image.tag`                    | Release version of login provider image                 | main                                    |
 | `login.user`                         | Username of user to create during installation          | admin@example.com                       |
@@ -57,7 +57,7 @@ This table lists the variables you are most likely to change. Take a look at the
 | `kratos.kratos.secrets.session`                        | **Array of strings for session secrets**                               | See values.yaml                                                |
 | `kratos.kratos.courier.smtp.connection_uri`            | **Config of SMTP server**                                              | **smtps://username:password@smtp.example.net:456/**            |
 | `kratos.kratos.courier.smtp.from_address`              | **From email address**                                                 | **no-reply@example.net**                                       |
-| `hydra.hydra.config.urls.self.issuer`| **Base URI of the oAuth server**                        | **https://sso.stackspin.example.net**                       |
+| `hydra.hydra.config.urls.self.issuer`| **Base URI of the OAuth server**                        | **https://sso.stackspin.example.net**                       |
 | `hydra.hydra.config.urls.login`      | **URI that will be used for the login page**            | **https://sso.stackspin.example.net/login**                 |
 | `hydra.hydra.config.urls.consent`    | **URI that will be used for permission checks**         | **https://sso.stackspin.example.net/consent**               |
 | `hydra.hydra.config.dsn`             | **Database endpoint for Hydra**                         | postgres://hydra:hydra@single-sign-on-postgresql:5432/hydra |
@@ -107,7 +107,7 @@ Commands:
 
 ### Registering clients
 
-To use OpenID Connect or oAuth you need to set up an oAuth Client for every
+To use OpenID Connect or OAuth you need to set up an OAuth Client for every
 application that needs to authenticate it's users. Setting up a client happens
 in two steps: registering the client with `single-sign-on`, and configuring the
 client application.
@@ -126,7 +126,7 @@ metadata:
   namespace: default
 spec:
   # Specifies the methods the client can use to retrieve access tokens from the
-  # oAuth server
+  # OAuth server
   grantTypes:
     - authorization_code
     - refresh_token
@@ -146,7 +146,7 @@ spec:
   # process is completed
   redirectUris:
     - https://dashboard.${domain}/_oauth/oidc
-  # Set the method that the oAUth client uses to authenticate agains the oAuth
+  # Set the method that the oAUth client uses to authenticate agains the OAuth
   # server i.e. to retrieve tokens or userinfo
   tokenEndpointAuthMethod: client_secret_post
 ```

docs/index.rst

@@ -6,7 +6,7 @@
 Welcome to single-sign-on's documentation!
 ==========================================
 
-This project provides a single sign on solution based on `Hydra`_ and `Kratos`_.
+This project provides a single sign-on solution based on `Hydra`_ and `Kratos`_.
 It also serves a small login and settings application.
 
 .. _Hydra: https://www.ory.sh/hydra/docs/