docs: add readthedocs documentation

.github/workflows/build.yml

@@ -14,7 +14,7 @@ jobs:
           python-version: 3.12
 
       - name: Install package
-        run: pip install -e .[dev]
+        run: pip install -e .[dev,docs]
 
       - name: Install make
         run: sudo apt update && sudo apt -y --no-install-recommends install make
@@ -37,11 +37,8 @@ jobs:
       - name: Build
         run: make build
 
-      - name: Upload coverage reports
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage
-          path: .artifacts/
+      - name: Build docs
+        run: make docs
 
       - name: CodeCov
         uses: codecov/[email protected]
@@ -58,5 +55,13 @@ jobs:
       - name: Upload coverage reports
         uses: actions/upload-artifact@v4
         with:
-          name: coverage-after
+          name: coverage
           path: .artifacts/
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: artifacts
+          path: |
+            dist/*.*
+            docs/_build/html

.gitignore

@@ -10,3 +10,5 @@ mantelo/version.py
 .mypy/
 .venv/
 __pycache__
+
+docs/_build

.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

CONTRIBUTING.md

@@ -48,6 +48,11 @@ make help
 Build
   build  Build the wheels and sdist.
 
+Documentation
+  docs   Generate the HTML documentation.
+  docs-clean  Remove docs build artifacts.
+  docs-open  Open the documentation locally (requires make docs to have ran).
+
 Development
   lint   Run ruff to format and lint (inside docker).
   test   Run tests with tox (inside docker).
@@ -77,5 +82,6 @@ This repository adheres to the
 1. Fork this repository, develop and test your changes
 2. Make sure that your changes do not decrease the test coverage
 3. Create signed commits that follow the conventional commits specification
-4. Submit a pull request
+4. If necessary, update the docs
+5. Submit a pull request
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all
+.PHONY: all help build docs lint test mypy export-realms
 
 default: help
 
@@ -13,6 +13,17 @@ build: ## Build the wheels and sdist.
 	rm -rf dist && \
 	python -m build
 
+##@ Documentation
+
+docs: ## Generate the HTML documentation.
+	cd docs && make html
+
+docs-clean: ## Remove docs build artifacts.
+	cd docs && make clean
+
+docs-open: ## Open the documentation locally (requires make docs to have ran).
+	open docs/_build/html/index.html
+
 ##@ Development
 
 lint: ## Run ruff to format and lint (inside docker).

README.md

@@ -2,9 +2,11 @@
 
 [![codecov](https://codecov.io/gh/derlin/mantelo/graph/badge.svg?token=5Y2O7B7342)](https://codecov.io/gh/derlin/mantelo)
 [![PyPI](https://img.shields.io/pypi/v/mantelo)](https://pypi.org/project/mantelo/)
-
+[![Documentation Status](https://readthedocs.org/projects/mantelo/badge/?version=latest)](https://mantelo.readthedocs.io/en/latest/?badge=latest)
 ---
 
+<img src="https://github.com/derlin/mantelo/blob/main/docs/_static/images/mantelo-text-900.png" alt="Mantelo" width="500">
+
 **✨✨ MANTELO is a super small yet super powerful tool for interacting with the Keycloak Admin API ✨✨**
 
 > Mantelo [manˈtelo], from German "*Mantel*", from Late Latin "*mantum*" means "*cloak*" in Esperanto.
@@ -16,7 +18,10 @@ slumber under the hood, it abstracts all the boring stuff such as authentication
 tokens), URL handling, serialization, and the processing of requests. This magic is made possible by
 the excellent [slumber](https://slumber.readthedocs.io/) library.
 
-⮕ Any endpoint your Keycloak supports, mantelo supports!
+Any endpoint your Keycloak supports, mantelo supports!
+
+
+⮕ **Documentation: https://mantelo.readthedocs.io/en/latest/**
 
 ---
 
@@ -26,7 +31,7 @@ the excellent [slumber](https://slumber.readthedocs.io/) library.
 - [🏁 Getting started](#-getting-started)
 - [🔐 Authenticate to Keycloak](#-authenticate-to-keycloak)
    * [Authenticating with username+password](#authenticating-with-usernamepassword)
-   * [Authenticating with a service account (client ID + secret)](#authenticating-with-a-service-account-client-id--secret)
+   * [Authenticating with client credentials (client ID + secret)](#authenticating-with-client-credentials-client-id--secret)
    * [Other ways of authenticating](#other-ways-of-authenticating)
 - [📡 Making calls](#-making-calls)
 - [💀 Exceptions](#-exceptions)

docs/00-getting_started.rst

@@ -0,0 +1,50 @@
+.. _getting_started:
+
+🏁 Getting started
+====================
+
+
+To get started, install the package:
+
+.. code-block:: python
+
+    pip install mantelo
+
+Now, assuming you have a Keycloak Server running, what's left is to:
+
+1. authenticate to Keycloak, :ref:`authentication`
+2. make calls, see :ref:`making_calls`
+
+For a quick test drive, use the
+`docker-compose.yml <https://github.com/derlin/mantelo/blob/main/docker-compose.yml>`_ included in
+the repo and start a Keycloak server locally using ``docker compose up``. Open a Python REPL and
+type:
+
+.. code-block:: python
+
+    from mantelo import KeycloakAdmin
+
+    # We assume the server is running on localhost:9090
+    # and the admin user is "admin" with password "admin"
+    c = KeycloakAdmin.from_username_password(
+        server_url="http://localhost:9090",
+        realm_name="master",
+        client_id="admin-cli",
+        username="admin",
+        password="admin",
+    )
+
+    # get the list of clients in realm "master"
+    c.clients.get()
+
+    # create a user
+    c.users.post({
+        "username": "test",
+        "enabled": True,
+        "credentials": [{"type": "password", "value": "test"}],
+    })
+    # get the user id
+    c.users.get(username="test")[0]["id"]
+
+    # ...
+

docs/01-authentication.rst

@@ -0,0 +1,157 @@
+.. _authentication:
+
+
+🔐 Authenticate to Keycloak
+===========================
+
+To authenticate to Keycloak, you can either use a username+password, or client credentials (client
+ID+client secret, also known as service account).
+
+The library takes care of fetching a token the first time you need it and keeping it fresh. By
+default, it tries to use the refresh token (if available) and always guarantees the token is valid
+for the next 30s.
+
+The authentication calls and the calls to the REST API are using the same
+:py:class:`requests.Session`, that can be passed at creation in case you need to add custom headers,
+proxies, etc.
+
+.. important::
+
+    A :py:class:`~.KeycloakAdmin` client is meant to interact with a single realm. It is however
+    possible to use another realm for authentication. You may change realms by setting
+    :py:attr:`~.KeycloakAdmin.realm_name`, but this requires your token to have permissions spanning
+    realms (e.g. authentication using the admin user).
+
+.. _authentication-password:
+
+Authenticating with username + password
+----------------------------------------
+
+Ensure your user has the right to interact with the endpoints you are interested in. In doubt or for
+testing, you can either use the admin user (not recommended) or create a user and assign it the
+``realm-management:realm-admin`` role (full access).
+
+.. hint::
+
+    Clients need to enable the "*Direct access grants*" authorization flow.
+    The client ``admin-cli``, which exists by default on all realms, is often used.
+
+Here is how to use :py:meth:`~.KeycloakAdmin.from_username_password` connect to the default realm
+with the admin user and ``admin-cli`` client:
+
+.. code:: python
+
+   from mantelo import KeycloakAdmin
+
+   client = KeycloakAdmin.from_username_password(
+       server_url="http://localhost:8080", # base Keycloak URL
+       realm_name="master",
+       # ↓↓ Authentication
+       client_id="admin-cli",
+       username="admin",
+       password="CHANGE-ME", # TODO
+   )
+
+This client will be able to make calls only to the ``master`` realm. If you want to authenticate to
+a realm that is different from the one you want to query, use the argument ``authentication_realm``:
+
+.. code:: python
+
+   from mantelo import KeycloakAdmin
+
+   client = KeycloakAdmin.from_username_password(
+       server_url="http://localhost:8080", # base Keycloak URL
+       realm_name="my-realm", # realm for querying
+       # ↓↓ Authentication
+       authentication_realm_name="master", # realm for authentication only
+       client_id="admin-cli",
+       username="admin",
+       password="CHANGE-ME",
+   )
+
+.. _authenticate-client:
+
+Authenticating with client credentials (client ID + secret)
+-----------------------------------------------------------
+
+It is also possible to authenticate through an OIDC client with a confidential access type.
+
+.. hint::
+
+    A confidential client should:
+
+    -  have "*Client authentication*" enabled,
+    -  support the "*Service accounts roles*" authentication flow,
+    -  have one or more service account roles granting access to Admin endpoints.
+
+    Go to your client's "Credentials" tab to find the client secret.
+
+Here is how to use :py:meth:`~.KeycloakAdmin.from_client_credentials` connect with a client:
+
+.. code:: python
+
+   from mantelo import KeycloakAdmin
+
+   client = KeycloakAdmin.from_client_credentials(
+       server_url="http://localhost:8080", # base Keycloak URL
+       realm_name="master",
+       # ↓↓ Authentication
+       client_id="my-client-name",
+       client_secret="59c3c211-2e56-4bb8-a07d-2961958f6185",
+   )
+
+This client will be able to make calls only to the ``master`` realm. If you want to authenticate to
+a realm that is different from the one you want to query, use the argument ``authentication_realm``:
+
+.. code:: python
+
+   from mantelo import KeycloakAdmin
+
+   client = KeycloakAdmin.from_client_credentials(
+       server_url="http://localhost:8080", # base Keycloak URL
+       realm_name="my-realm", # realm for querying
+       # ↓↓ Authentication
+       authentication_realm_name="master", # realm for authentication only
+       client_id="my-client-name",
+       client_secret="59c3c211-2e56-4bb8-a07d-2961958f6185",
+   )
+
+Other ways of authenticating
+----------------------------
+
+The supported authentication methods should be enough. If you need more, a pull request or an issue
+is welcome! But just in case, here are some ways to make it more complicated 😉.
+
+To create a :py:class:`~.KeycloakAdmin`, you only need a method that returns a token. For example,
+you can use an existing token directly (not recommended, as tokens are short-lived):
+
+.. code:: python
+
+   from mantelo.client import BearerAuth, KeycloakAdmin
+
+   KeycloakAdmin(
+       server_url="http://localhost:8080",
+       realm_name="master",
+       auth=BearerAuth(lambda: "my-token"),
+   )
+
+If you want to go further, you can create your own :py:class:`~.Connection` class (or extend the
+:py:class:`~.OpenidConnection`), and pass its :py:meth:`~.OpenidConnection.token` method to the
+:py:class:`~.BearerAuth`:
+
+.. code:: python
+
+   from mantelo.client import BearerAuth, KeycloakAdmin
+   from mantelo.connection import Connection
+
+   class MyConnection(Connection):
+       def token(self):
+           return "<do-something-here>"
+
+   connection = MyConnection()
+
+   KeycloakAdmin(
+       server_url="http://localhost:8080",
+       realm_name="master",
+       auth=BearerAuth(connection.token),
+   )