[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [28019] trunk/blender/source/blender/ python: document bpy.types.Struct methods C methods, currently only keyframe_delete() and keyframe_insert() have useful docstrings.

[Campbell Barton]

Revision: 28019
          http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=28019
Author:   campbellbarton
Date:     2010-04-06 00:37:09 +0200 (Tue, 06 Apr 2010)

Log Message:
-----------
document bpy.types.Struct methods C methods, currently only keyframe_delete() and keyframe_insert() have useful docstrings.

http://www.blender.org/documentation/250PythonDoc/bpy.types.Struct.html?highlight=bpy.types.struct#bpy.types.Struct.keyframe_insert

Modified Paths:
--------------
    trunk/blender/source/blender/python/doc/sphinx_doc_gen.py
    trunk/blender/source/blender/python/intern/bpy_rna.c

Modified: trunk/blender/source/blender/python/doc/sphinx_doc_gen.py
===================================================================
--- trunk/blender/source/blender/python/doc/sphinx_doc_gen.py	2010-04-05 21:06:32 UTC (rev 28018)
+++ trunk/blender/source/blender/python/doc/sphinx_doc_gen.py	2010-04-05 22:37:09 UTC (rev 28019)
@@ -43,6 +43,10 @@
 import rna_info
 reload(rna_info)
 
+# lame, python wont give some access
+MethodDescriptorType = type(dict.get)
+GetSetDescriptorType = type(int.real)
+
 EXAMPLE_SET = set()
 EXAMPLE_SET_USED = set()
 
@@ -144,11 +148,6 @@
 
 def pymodule2sphinx(BASEPATH, module_name, module, title):
     import types
-    # lame, python wont give some access
-    MethodDescriptorType = type(dict.get)
-    GetSetDescriptorType = type(int.real)
-    
-    
 
     filepath = os.path.join(BASEPATH, module_name + ".rst")
     
@@ -180,7 +179,7 @@
     
     classes = []
 
-    for attribute in dir(module):
+    for attribute in sorted(dir(module)):
         if not attribute.startswith("_"):
             value = getattr(module, attribute)
 
@@ -194,6 +193,14 @@
                 py_c_func2sphinx("", fw, attribute, value, is_class=False)
             elif value_type == type:
                 classes.append((attribute, value))
+            elif value_type in (bool, int, float, str, tuple):
+                # constant, not much fun we can do here except to list it.
+                # TODO, figure out some way to document these!
+                fw(".. data:: %s\n\n" % attribute)
+                write_indented_lines("   ", fw, "constant value %s" % repr(value), False)
+                fw("\n")
+            else:
+                print("\tnot documenting %s.%s" % (module_name, attribute))
             # TODO, more types...
     
     # write collected classes now
@@ -472,6 +479,15 @@
             pyfunc2sphinx("   ", fw, identifier, py_func, is_class=True)
         del py_funcs, py_func
 
+        # c/python methods, only for the base class
+        if struct.identifier == "Struct":
+            for attribute, descr in bpy.types.Struct.__bases__[0].__dict__.items():
+                if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
+                    if descr.__doc__:
+                        write_indented_lines("   ", fw, descr.__doc__, False)
+                        write_example_ref("   ", fw, struct.identifier + "." + attribute)
+                        fw("\n")
+
         if struct.references:
             # use this otherwise it gets in the index for a normal heading.
             fw(".. rubric:: References\n\n")

Modified: trunk/blender/source/blender/python/intern/bpy_rna.c
===================================================================
--- trunk/blender/source/blender/python/intern/bpy_rna.c	2010-04-05 21:06:32 UTC (rev 28018)
+++ trunk/blender/source/blender/python/intern/bpy_rna.c	2010-04-05 22:37:09 UTC (rev 28019)
@@ -1711,6 +1711,18 @@
 	return 0; /* success */
 }
 
+static char pyrna_struct_keyframe_insert_doc[] =
+".. function:: keyframe_insert(path, index=-1, frame=bpy.context.scene.frame_current)\n"
+"\n"
+"   Returns a boolean, True if the keyframe is set.\n"
+"\n"
+"   :arg path: path to the property to key, analogous to the fcurve's data path.\n"
+"   :type path: string\n"
+"   :arg index: array index of the property to key. Defaults to -1 which will key all indicies or a single channel if the property is not an array.\n"
+"   :type index: int\n"
+"   :arg frame: The frame on which the keyframe is inserted, defaulting to the current frame.\n"
+"   :type frame: float";
+
 static PyObject *pyrna_struct_keyframe_insert(BPy_StructRNA *self, PyObject *args)
 {
 	PyObject *result;
@@ -1728,6 +1740,18 @@
 	return result;
 }
 
+static char pyrna_struct_keyframe_delete_doc[] =
+".. function:: keyframe_delete(path, index=-1, frame=bpy.context.scene.frame_current)\n"
+"\n"
+"   Returns a boolean, True if the keyframe is removed.\n"
+"\n"
+"   :arg path: path to the property to remove a key, analogous to the fcurve's data path.\n"
+"   :type path: string\n"
+"   :arg index: array index of the property to remove a key. Defaults to -1 removing all indicies or a single channel if the property is not an array.\n"
+"   :type index: int\n"
+"   :arg frame: The frame on which the keyframe is deleted, defaulting to the current frame.\n"
+"   :type frame: float";
+
 static PyObject *pyrna_struct_keyframe_delete(BPy_StructRNA *self, PyObject *args)
 {
 	PyObject *result;
@@ -2714,8 +2738,8 @@
 	{"as_pointer", (PyCFunction)pyrna_struct_as_pointer, METH_NOARGS, NULL},
 
 	/* maybe this become and ID function */
-	{"keyframe_insert", (PyCFunction)pyrna_struct_keyframe_insert, METH_VARARGS, NULL},
-	{"keyframe_delete", (PyCFunction)pyrna_struct_keyframe_delete, METH_VARARGS, NULL},
+	{"keyframe_insert", (PyCFunction)pyrna_struct_keyframe_insert, METH_VARARGS, pyrna_struct_keyframe_insert_doc},
+	{"keyframe_delete", (PyCFunction)pyrna_struct_keyframe_delete, METH_VARARGS, pyrna_struct_keyframe_delete_doc},
 	{"driver_add", (PyCFunction)pyrna_struct_driver_add, METH_VARARGS, NULL},
 	{"is_property_set", (PyCFunction)pyrna_struct_is_property_set, METH_VARARGS, NULL},
 	{"is_property_hidden", (PyCFunction)pyrna_struct_is_property_hidden, METH_VARARGS, NULL},