From 47f2b1007fc29ceaf82f88c508884519dee521df Mon Sep 17 00:00:00 2001
From: Steven Bal <steven@maykinmedia.nl>
Date: Tue, 20 Feb 2024 10:09:54 +0100
Subject: [PATCH] :memo: [#88] Add reference and changelog sections to RTD

---
 docs/changelog.rst              |  1 +
 docs/index.rst                  | 24 ++++++++++++++++++++----
 docs/reference.rst              | 11 +++++++++++
 mozilla_django_oidc_db/utils.py |  3 +++
 4 files changed, 35 insertions(+), 4 deletions(-)
 create mode 100644 docs/changelog.rst
 create mode 100644 docs/reference.rst

diff --git a/docs/changelog.rst b/docs/changelog.rst
new file mode 100644
index 0000000..565b052
--- /dev/null
+++ b/docs/changelog.rst
@@ -0,0 +1 @@
+.. include:: ../CHANGELOG.rst
diff --git a/docs/index.rst b/docs/index.rst
index 3798671..3d99a0f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,14 +14,26 @@ Database-backed settings for mozilla-django-oidc, with modified unique identifie
 Features
 ========
 
-* ...
-* ...
+* Thin layer on top of `mozilla-django-oidc`_
+* Allows configuration of OpenID Connect variables via django-solo
+* Overrides `mozilla-django-oidc`_ default behaviour, using the ``sub`` claim
+  instead of the ``email`` claim as unique identifier for users
+
+``mozilla-django-oidc-db`` provides a database singleton for several configuration
+variables required for ``mozilla-django-oidc``, moving them from deploy-time to run-time.
+This enables modification of the configuration, without having to restart the application.
+
+Additionally, ``mozilla-django-oidc-db`` by default uses the ``sub`` (subject) claim
+instead of the ``email`` claim as the unique identifier for users in the RP (Relying Party) application.
+Using ``email`` as the unique identifier is not recommended, as mentioned in the `OpenID Connect specification`_.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    quickstart
+   reference
+   changelog
 
 
 
@@ -32,8 +44,8 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
-.. |build-status| image:: https://travis-ci.org/maykinmedia/mozilla_django_oidc_db.svg?branch=master
-    :target: https://travis-ci.org/maykinmedia/mozilla_django_oidc_db
+.. |build-status| image:: https://github.com/maykinmedia/mozilla-django-oidc-db/workflows/Run%20CI/badge.svg
+    :target: https://github.com/maykinmedia/mozilla-django-oidc-db/actions?query=workflow%3A%22Run+CI%22
 
 .. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/psf/black
@@ -48,3 +60,7 @@ Indices and tables
 
 .. |pypi-version| image:: https://img.shields.io/pypi/v/mozilla_django_oidc_db.svg
     :target: https://pypi.org/project/mozilla_django_oidc_db/
+
+.. _mozilla-django-oidc: https://github.com/mozilla/mozilla-django-oidc
+
+.. _OpenID Connect specification: https://openid.net/specs/openid-connect-core-1_0.html#ClaimStability
diff --git a/docs/reference.rst b/docs/reference.rst
new file mode 100644
index 0000000..4bd0f85
--- /dev/null
+++ b/docs/reference.rst
@@ -0,0 +1,11 @@
+=========
+Reference
+=========
+
+Public API documentation.
+
+Utils
+=====
+
+.. automodule:: mozilla_django_oidc_db.utils
+    :members:
diff --git a/mozilla_django_oidc_db/utils.py b/mozilla_django_oidc_db/utils.py
index 95c08a5..a92793a 100644
--- a/mozilla_django_oidc_db/utils.py
+++ b/mozilla_django_oidc_db/utils.py
@@ -22,6 +22,9 @@ def obfuscate_claim_value(value: Any) -> str:
 
 
 def obfuscate_claims(claims: dict, claims_to_obfuscate: List[str]) -> dict:
+    """
+    Obfuscates the specified claims in the specified claims dict
+    """
     copied_claims = deepcopy(claims)
     for claim_name in claims_to_obfuscate:
         # NOTE: this does not support claim names that have dots in them