PyDocs: Add Macro example

- Adds a doc string for the Macro class
- Adds a basic example

Fixes #blender-manual/issues/51387

doc/python_api/examples/bpy.types.Macro.py

@@ -0,0 +1,47 @@
+"""
+Example Macro
++++++++++++++
+
+This example creates a simple macro operator that
+moves the active object and then rotates it.
+It demonstrates:
+
+- Defining a macro operator class.
+- Registering it and defining sub-operators.
+- Setting property values for each step.
+"""
+
+import bpy
+
+class OBJECT_OT_simple_macro(bpy.types.Macro):
+    bl_idname = "object.simple_macro"
+    bl_label = "Simple Transform Macro"
+    bl_options = {'REGISTER', 'UNDO'}
+
+    @classmethod
+    def poll(cls, context):
+        return context.active_object is not None
+
+def register():
+    bpy.utils.register_class(OBJECT_OT_simple_macro)
+
+    # Define steps after registration and set operator values via .properties
+    step = OBJECT_OT_simple_macro.define("transform.translate")
+    props = step.properties
+    props.value = (1.0, 0.0, 0.0)
+    props.constraint_axis = (True, False, False)
+
+    step = OBJECT_OT_simple_macro.define("transform.rotate")
+    props = step.properties
+    props.value = 0.785398  # 45 degrees in radians
+    props.orient_axis = 'Z'
+
+
+def unregister():
+    bpy.utils.unregister_class(OBJECT_OT_simple_macro)
+
+if __name__ == "__main__":
+    register()
+
+    # To run the macro:
+    bpy.ops.object.simple_macro()

scripts/modules/bpy_types.py

@@ -1019,6 +1019,10 @@ class Operator(_StructRNA, metaclass=_RNAMeta):
 
 
 class Macro(_StructRNA):
+    """
+    Strings multiple operators together and invokes them sequentially as a single operator.
+    """
+
     # _types is imported before ops is defined
     # so we have to do a local import on each run
     __slots__ = ()