docs: add opengraph meta

Add proper description and social preview to the readthedocs site.
derlin · Mar 24, 2024 · 0310e41 · 0310e41
1 parent 04cc4d7
commit 0310e41
Show file tree

Hide file tree

Showing 9 changed files with 38 additions and 6 deletions.
diff --git a/docs/00-getting_started.rst b/docs/00-getting_started.rst
@@ -1,3 +1,8 @@
+:og:description: Get started with mantelo.
+
+.. meta::
+   :description: Get started with mantelo.
+
 .. _getting_started:
 
 🏁 Getting started

diff --git a/docs/01-authentication.rst b/docs/01-authentication.rst
@@ -1,5 +1,9 @@
-.. _authentication:
+:og:description: How to authenticate to Keycloak using mantelo.
+
+.. meta::
+   :description: How to authenticate to Keycloak using mantelo.
 
+.. _authentication:
 
 🔐 Authenticate to Keycloak
 ===========================

diff --git a/docs/02-making-calls.rst b/docs/02-making-calls.rst
@@ -1,13 +1,15 @@
-.. _making_calls:
+:og:description: How to make calls to the Keycloak Admin API using mantelo.
+
+.. meta::
+   :description: How to make calls to the Keycloak Admin API using mantelo.
 
-.. role:: python(code)
-   :language: python
+.. _making_calls:
 
 📡 Making calls
 ===============
 
 Once you have configured how to authenticate to Keycloak, the rest is easy-peasy. mantelo **starts
-with the URL ``<server-url>/admin/realms/<realm-name>``** and constructs the URL from there,
+with the URL** ``<server-url>/admin/realms/<realm-name>`` and constructs the URL from there,
 depending on how you call the client.
 
 The return value is the HTTP response content as a :python:`dict` (parsed from the JSON response). In

diff --git a/docs/90-api.rst b/docs/90-api.rst
@@ -1,3 +1,8 @@
+:og:description: The API documentation for Mantelo.
+
+.. meta::
+   :description: The API documentation for Mantelo.
+
 .. _api:
 
 The API Documentation

diff --git a/docs/_static/images/mantelo-social-preview.png b/docs/_static/images/mantelo-social-preview.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -28,6 +28,7 @@
     "sphinx.ext.intersphinx",
     "autoapi.extension",
     "sphinx_copybutton",
+    "sphinxext.opengraph",
 ]
 
 autoapi_type = "python"
@@ -52,6 +53,10 @@
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+rst_prolog = """
+.. role:: python(code)
+   :language: python
+"""
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -84,3 +89,8 @@
         }
     ],
 }
+
+ogp_site_url = "https://mantelo.readthedocs.io/en/latest/"
+ogp_social_cards = {
+    "image": "_static/images/mantelo-social-preview.png",
+}
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,3 +1,8 @@
+:og:description: Mantelo is a super small yet super powerful Python library for interacting with the Keycloak Admin API.
+
+.. meta::
+   :description: Mantelo is a super small yet super powerful Python library for interacting with the Keycloak Admin API.
+
 Mantelo: A Keycloak Admin REST Api Client for Python
 =====================================================
 

diff --git a/mantelo/exceptions.py b/mantelo/exceptions.py
@@ -6,7 +6,7 @@
 @frozen
 class AuthenticationException(Exception):
     """
-    Exception raised when the authentication fails with "401 Unauthorized" status code.
+    Exception raised when the authentication request fails with a `401 Unauthorized` status code.
     """
 
     error: str

diff --git a/pyproject.toml b/pyproject.toml
@@ -66,6 +66,7 @@ docs = [
   "sphinx-book-theme",
   "sphinx-autoapi",
   "sphinx-copybutton",
+  "sphinxext-opengraph",
 ]