From f6eb4c7d06ddf37bcc7d70371814c20ab0f62e7c Mon Sep 17 00:00:00 2001
From: Charles Leifer <coleifer@gmail.com>
Date: Thu, 6 Jun 2024 11:33:25 -0500
Subject: [PATCH] Doc for SubclassAwareMetadata.

[skip ci]
---
 docs/peewee/api.rst | 32 +++++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/docs/peewee/api.rst b/docs/peewee/api.rst
index f05973b47..939d0ff68 100644
--- a/docs/peewee/api.rst
+++ b/docs/peewee/api.rst
@@ -3982,7 +3982,37 @@ Model
 
 .. py:class:: SubclassAwareMetadata
 
-    Metadata subclass that tracks :py:class:`Model` subclasses.
+    Metadata subclass that tracks :py:class:`Model` subclasses. Useful for
+    when you need to track all models in a project.
+
+    Example:
+
+    .. code-block:: python
+
+        from peewee import SubclassAwareMetadata
+
+        class Base(Model):
+            class Meta:
+                database = db
+                model_metadata_class = SubclassAwareMetadata
+
+        # Create 3 model classes that inherit from Base.
+        class A(Base): pass
+        class B(Base): pass
+        class C(Base): pass
+
+        # Now let's make a helper for changing the `schema` for each Model.
+        def change_schema(schema):
+            def _update(model):
+                model._meta.schema = schema
+            return _update
+
+        # Set all models to use "schema1", e.g. "schema1.a", "schema1.b", etc.
+        # Will apply the function to every subclass of Base.
+        Base._meta.map_models(change_schema('schema1'))
+
+        # Set all models to use "schema2", e.g. "schema2.a", "schema2.b", etc.
+        Base._meta.map_models(change_schema('schema2'))
 
     .. py:method:: map_models(fn)