bpy.types.libraries.load sphinx doc & examples (doc system needed some updates).

http://www.blender.org/documentation/blender_python_api_2_56_3/bpy.types.BlendDataLibraries.html#bpy.types.BlendDataLibraries.load

doc/python_api/examples/bpy.types.BlendDataLibraries.load.py

@@ -0,0 +1,23 @@
+import bpy
+
+filepath = "//link_library.blend"
+
+# load a single scene we know the name of.
+with bpy.data.libraries.load(filepath) as (data_from, data_to):
+    data_to.scenes = ["Scene"]
+
+
+# load all meshes
+with bpy.data.libraries.load(filepath) as (data_from, data_to):
+    data_to.meshes = data_from.meshes
+
+
+# link all objects starting with 'A'
+with bpy.data.libraries.load(filepath, link=True) as (data_from, data_to):
+    data_to.objects = [name for name in data_from.objects if name.startswith("A")]
+
+
+# append everything
+with bpy.data.libraries.load(filepath) as (data_from, data_to):
+    for attr in dir(data_to):
+        setattr(data_to, attr, getattr(data_from, attr))

doc/python_api/sphinx_doc_gen.py

@@ -279,6 +279,13 @@ def py_c_func2sphinx(ident, fw, module_name, type_name, identifier, py_func, is_
         fw(ident + ".. function:: %s()\n\n" % identifier)
         fw(ident + "   " + undocumented_message(module_name, type_name, identifier))
 
+    if is_class:
+        write_example_ref(ident + "   ", fw, module_name + "." + type_name + "." + identifier)
+    else:
+        write_example_ref(ident + "   ", fw, module_name + "." + identifier)
+
+    fw("\n")
+
 
 def pyprop2sphinx(ident, fw, identifier, py_prop):
     '''
@@ -356,7 +363,7 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
             elif value_type in (types.BuiltinMethodType, types.BuiltinFunctionType):  # both the same at the moment but to be future proof
                 # note: can't get args from these, so dump the string as is
                 # this means any module used like this must have fully formatted docstrings.
-                py_c_func2sphinx("", fw, module_name, module, attribute, value, is_class=False)
+                py_c_func2sphinx("", fw, module_name, None, attribute, value, is_class=False)
             elif value_type == type:
                 classes.append((attribute, value))
             elif value_type in (bool, int, float, str, tuple):
@@ -655,6 +662,12 @@ def pyrna2sphinx(BASEPATH):
             pyfunc2sphinx("   ", fw, identifier, py_func, is_class=True)
         del py_funcs, py_func
 
+        py_funcs = struct.get_py_c_functions()
+        py_func = None
+
+        for identifier, py_func in py_funcs:
+            py_c_func2sphinx("   ", fw, "bpy.types", struct.identifier, identifier, py_func, is_class=True)
+
         lines = []
 
         if struct.base or _BPY_STRUCT_FAKE:

release/scripts/modules/rna_info.py

@@ -152,6 +152,14 @@ class InfoStructRNA:
                 functions.append((identifier, attr))
         return functions
 
+    def get_py_c_functions(self):
+        import types
+        functions = []
+        for identifier, attr in self._get_py_visible_attrs():
+            if type(attr) in (types.BuiltinMethodType, types.BuiltinFunctionType):
+                functions.append((identifier, attr))
+        return functions
+
     def __str__(self):
 
         txt = ""

source/blender/python/intern/bpy_library.c

@@ -155,7 +155,19 @@ PyTypeObject bpy_lib_Type = {
 	NULL
 };
 
-
+static char bpy_lib_load_doc[] =
+".. method:: load(filepath, link=False, relative=False)\n"
+"\n"
+"   Returns a context manager which exposes 2 library objects on entering.\n"
+"   Each object has attributes matching bpy.data which are lists of strings to be linked.\n"
+"\n"
+"   :arg filepath: The path to a blend file.\n"
+"   :type filepath: string\n"
+"   :arg link: When False reference to the original file is lost.\n"
+"   :type link: bool\n"
+"   :arg relative: When True the path is stored relative to the open blend file.\n"
+"   :type relative: bool\n"
+;
 static PyObject *bpy_lib_load(PyObject *UNUSED(self), PyObject *args, PyObject *kwds)
 {
 	static const char *kwlist[] = {"filepath", "link", "relative", NULL};
@@ -168,8 +180,8 @@ static PyObject *bpy_lib_load(PyObject *UNUSED(self), PyObject *args, PyObject *
 
 	ret= PyObject_New(BPy_Library, &bpy_lib_Type);
 
-	BLI_strncpy(ret->relpath, filename, sizeof(BPy_Library));
-	BLI_strncpy(ret->abspath, filename, sizeof(BPy_Library));
+	BLI_strncpy(ret->relpath, filename, sizeof(ret->relpath));
+	BLI_strncpy(ret->abspath, filename, sizeof(ret->abspath));
 	BLI_path_abs(ret->abspath, G.main->name);
 
 	ret->blo_handle= NULL;
@@ -342,7 +354,7 @@ static PyObject *bpy_lib_dir(BPy_Library *self)
 
 int bpy_lib_init(PyObject *mod_par)
 {
-	static PyMethodDef load_meth= {"load", (PyCFunction)bpy_lib_load, METH_STATIC|METH_VARARGS|METH_KEYWORDS};
+	static PyMethodDef load_meth= {"load", (PyCFunction)bpy_lib_load, METH_STATIC|METH_VARARGS|METH_KEYWORDS, bpy_lib_load_doc};
 	PyModule_AddObject(mod_par, "_library_load", PyCFunction_New(&load_meth, NULL));
 
 	if(PyType_Ready(&bpy_lib_Type) < 0)