docs: add more examples

Add some real examples on how to create, list, delete users, etc.
The code snippets are tested using the sphinx doctest extension.

.github/workflows/build.yml

@@ -37,6 +37,9 @@ jobs:
       - name: Build
         run: make build
 
+      - name: Test docs
+        run: make docs-test
+
       - name: Build docs
         run: make docs
 
@@ -65,3 +68,4 @@ jobs:
           path: |
             dist/*.*
             docs/_build/html
+            docs/_build/doctest

.github/workflows/weekly.yml

@@ -25,3 +25,6 @@ jobs:
 
       - name: Test
         run: make test
+
+      - name: Docs test
+        run: make docs-test

Makefile

@@ -24,6 +24,10 @@ docs-clean: ## Remove docs build artifacts.
 docs-open: ## Open the documentation locally (requires make docs to have ran).
 	open docs/_build/html/index.html
 
+docs-test: ## Test the documentation code snippets.
+	docker compose up -d --wait keycloak
+	cd docs && make doctest
+
 ##@ Development
 
 lint: ## Run ruff to format and lint (inside docker).

docs/03-examples.rst

@@ -0,0 +1,88 @@
+:og:description: Example API calls with Mantelo.
+
+.. meta::
+   :description: Example API calls with Mantelo.
+
+
+.. _examples:
+
+📓 Examples
+===========
+
+Assuming you created a client (see :ref:`authentication`), here are some examples of how to interact with the Keycloak Admin API using Mantelo.
+Don't hesitate to create an `issue <https://github.com/derlin/mantelo/issues/new/choose>` if you want to see more examples or if you have any questions.
+
+Create, update, and delete a user
+---------------------------------
+
+.. testsetup:: *
+
+    from mantelo import KeycloakAdmin
+
+    client = KeycloakAdmin.from_username_password(
+           server_url="http://localhost:9090",
+           realm_name="master",
+           client_id="admin-cli",
+           username="admin",
+           password="admin",
+    )
+
+    user_id = None
+
+
+.. doctest::
+
+    # Create a new user
+    >>> client.users.post({
+    ...    "username": "test_user",
+    ...    "email": "[email protected]",
+    ...    "enabled": True,
+    ...    "emailVerified": True,
+    ... })
+    b''
+
+    # Get the ID of the newly created user
+    >>> user_id = client.users.get(username="test_user")[0]["id"]
+
+    >>> client.users(user_id).get()['username']
+    'test_user'
+
+    # Add some password credentials
+    >>> client.users(user_id).put({"credentials": [{"type": "password", "value": "CHANGE_ME"}]})
+
+    >>> client.users(user_id).credentials.get()
+    [{'id': ..., 'type': 'password', 'createdDate': ..., 'credentialData': ...}]
+
+    # Delete the user
+    >>> client.users(user_id).delete()
+    True
+
+List and count resources
+-------------------------
+
+.. doctest::
+
+    # Count the number of users
+    >>> client.users.count.get()
+    1
+
+    # List the first 10 users in the realm
+    >>> client.users.get(max=10)
+    [{...}]
+
+    # List the next 10 users in the realm (in this case, we don't have any)
+    >>> client.users.get(max=10, first=10)
+    []
+
+    # List all clients in the realm
+    >>> client.clients.get()
+    [{...}, {...}, ...]
+
+    # List roles associated with the broker client
+    >>> c_uid = client.clients.get(clientId="broker")[0]["id"]
+    >>> client.clients(c_uid).roles.get()
+    [{'id': ..., 'name': 'read-token', 'description': ..., 'composite': False, 'clientRole': True, 'containerId': ...}]
+
+    # Count the active sessions for a client
+    >>> client.clients(c_uid).session_count.get()
+    {'count': 0}

docs/conf.py

@@ -29,6 +29,7 @@
     "autoapi.extension",
     "sphinx_copybutton",
     "sphinxext.opengraph",
+    "sphinx.ext.doctest",
 ]
 
 autoapi_type = "python"

docs/index.rst

@@ -28,6 +28,7 @@ the excellent `slumber <https://slumber.readthedocs.io/>`_ library.
    00-getting_started
    01-authentication
    02-making-calls
+   03-examples
    90-api
 
 -------------------