examples for keyframing nested paths. based on report from user der_On's report [#25746]

3 files changed, 48 insertions, 3 deletions

diff --git a/doc/python_api/examples/bpy.types.bpy_struct.keyframe_insert.1.py b/doc/python_api/examples/bpy.types.bpy_struct.keyframe_insert.1.py
new file mode 100644
index 00000000000..c1cae149495
--- /dev/null
+++ b/doc/python_api/examples/bpy.types.bpy_struct.keyframe_insert.1.py
@@ -0,0 +1,31 @@
+"""
+Keying Nested Properties
+++++++++++++++++++++++++
+
+Note that when keying data paths which contain nested properties this must be
+done from the :class:`ID` subclass, in this case the :class:`Armature` rather
+then the bone.
+"""
+
+import bpy
+from bpy.props import PointerProperty
+
+
+# define a nested property
+class MyPropGroup(bpy.types.PropertyGroup):
+    nested = bpy.props.FloatProperty(name="Nested", default=0.0)
+
+# register it so its available for all bones
+bpy.utils.register_class(MyPropGroup)
+bpy.types.Bone.my_prop = PointerProperty(type=MyPropGroup,
+                                         name="MyProp")
+
+# get a bone
+obj = bpy.data.objects["Armature"]
+arm = obj.data
+
+# set the keyframe at frame 1
+arm.bones["Bone"].my_prop_group.nested = 10
+arm.keyframe_insert(data_path='bones["Bone"].my_prop.nested',
+                    frame=1,
+                    group="Nested Group")
diff --git a/doc/python_api/examples/bpy.types.bpy_struct.keyframe_insert.py b/doc/python_api/examples/bpy.types.bpy_struct.keyframe_insert.py
new file mode 100644
index 00000000000..91c1b6f8178
--- /dev/null
+++ b/doc/python_api/examples/bpy.types.bpy_struct.keyframe_insert.py
@@ -0,0 +1,14 @@
+"""
+Basic Keyframing
+++++++++++++++++
+
+This is the most simple example of inserting a keyframe from python.
+"""
+
+import bpy
+
+obj = bpy.context.object
+
+# set the keyframe at frame 1
+obj.location = 3.0, 4.0, 10.0
+obj.keyframe_insert(data_path="location", frame=1)
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py
index b479b19c297..3eedd658406 100644
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@@ -27,7 +27,7 @@ For HTML generation
 -------------------
 - Run this script from blenders root path once you have compiled blender
 
-    ./blender.bin -b -P doc/python_api/sphinx_doc_gen.py
+    ./blender.bin --background --python doc/python_api/sphinx_doc_gen.py
 
   This will generate python files in doc/python_api/sphinx-in/,
   assuming that ./blender.bin is or links to the blender executable
@@ -74,7 +74,7 @@ else:
         "mathutils.geometry",
     )
 
-    FILTER_BPY_TYPES = ("PropertyGroup", "Panel", "Menu", "Operator", "RenderEngine")  # allow
+    FILTER_BPY_TYPES = ("bpy_struct", "Panel", "Menu", "Operator", "RenderEngine")  # allow
     FILTER_BPY_OPS = ("import.scene", )  # allow
 
     # for quick rebuilds
@@ -272,7 +272,7 @@ def py_descr2sphinx(ident, fw, descr, module_name, type_name, identifier):
     else:
         raise TypeError("type was not GetSetDescriptorType, MethodDescriptorType or ClassMethodDescriptorType")
 
-    write_example_ref(ident, fw, module_name + "." + type_name + "." + identifier)
+    write_example_ref(ident + "   ", fw, module_name + "." + type_name + "." + identifier)
     fw("\n")