Merged changes in the trunk up to revision 40096.

Conflicts resolved:
source/blender/makesrna/intern/rna_scene.c
source/blender/python/intern/CMakeLists.txt

Note for branch builders: Enabling Blender Player may cause linker errors.

8 files changed, 846 insertions, 122 deletions

diff --git a/doc/python_api/examples/bge.texture.1.py b/doc/python_api/examples/bge.texture.1.py
index faa0ae736e8..4be6f51de67 100644
--- a/doc/python_api/examples/bge.texture.1.py
+++ b/doc/python_api/examples/bge.texture.1.py
@@ -14,7 +14,7 @@ def createTexture(cont):
     object = cont.owner
 
     # get the reference pointer (ID) of the internal texture
-    ID = texture.materialID(obj, 'IMoriginal.png')
+    ID = texture.materialID(object, 'IMoriginal.png')
 
     # create a texture object
     object_texture = texture.Texture(object, ID)
diff --git a/doc/python_api/examples/bpy.types.Operator.py b/doc/python_api/examples/bpy.types.Operator.py
index 52edfa0a61b..0981712e1ff 100644
--- a/doc/python_api/examples/bpy.types.Operator.py
+++ b/doc/python_api/examples/bpy.types.Operator.py
@@ -21,7 +21,7 @@ class HelloWorldOperator(bpy.types.Operator):
         print("Hello World")
         return {'FINISHED'}
 
-bpy.utils.register_class(SimpleOperator)
+bpy.utils.register_class(HelloWorldOperator)
 
 # test call to the newly defined operator
 bpy.ops.wm.hello_world()
diff --git a/doc/python_api/rst/bgl.rst b/doc/python_api/rst/bgl.rst
index 5f3158bf5dd..61400351d16 100644
--- a/doc/python_api/rst/bgl.rst
+++ b/doc/python_api/rst/bgl.rst
@@ -56,9 +56,9 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    :type n: int
    :arg n: Specifies the number of textures to be queried.
-   :type textures: :class:`Buffer` object I{type GL_INT}
+   :type textures: :class:`bgl.Buffer` object I{type GL_INT}
    :arg textures: Specifies an array containing the names of the textures to be queried
-   :type residences: :class:`Buffer` object I{type GL_INT}(boolean)
+   :type residences: :class:`bgl.Buffer` object I{type GL_INT}(boolean)
    :arg residences: An array in which the texture residence status in returned.
       The residence status of a texture named by an element of textures is
       returned in the corresponding element of residences.
@@ -101,7 +101,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :type xmove, ymove: float
    :arg xmove, ymove: Specify the x and y offsets to be added to the current raster position after
       the bitmap is drawn.
-   :type bitmap: :class:`Buffer` object I{type GL_BYTE}
+   :type bitmap: :class:`bgl.Buffer` object I{type GL_BYTE}
    :arg bitmap: Specifies the address of the bitmap image.
 
 
@@ -139,7 +139,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :arg n: Specifies the number of display lists to be executed.
    :type type: Enumerated constant
    :arg type: Specifies the type of values in lists.
-   :type lists: :class:`Buffer` object
+   :type lists: :class:`bgl.Buffer` object
    :arg lists: Specifies the address of an array of name offsets in the display list.
       The pointer type is void because the offsets can be bytes, shorts, ints, or floats,
       depending on the value of type.
@@ -217,7 +217,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    :type plane: Enumerated constant
    :arg plane: Specifies which clipping plane is being positioned.
-   :type equation: :class:`Buffer` object I{type GL_FLOAT}(double)
+   :type equation: :class:`bgl.Buffer` object I{type GL_FLOAT}(double)
    :arg equation: Specifies the address of an array of four double- precision
       floating-point values. These values are interpreted as a plane equation.
 
@@ -340,7 +340,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    :type n: int
    :arg n: Specifies the number of textures to be deleted
-   :type textures: :class:`Buffer` I{GL_INT}
+   :type textures: :class:`bgl.Buffer` I{GL_INT}
    :arg textures: Specifies an array of textures to be deleted
 
 
@@ -413,7 +413,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :arg format: Specifies the format of the pixel data.
    :type type: Enumerated constant
    :arg type: Specifies the data type for pixels.
-   :type pixels: :class:`Buffer` object
+   :type pixels: :class:`bgl.Buffer` object
    :arg pixels: Specifies a pointer to the pixel data.
 
 
@@ -512,7 +512,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :type type: Enumerated constant
    :arg type: Specifies a symbolic constant that describes the information that
       will be returned for each vertex.
-   :type buffer: :class:`Buffer` object I{GL_FLOAT}
+   :type buffer: :class:`bgl.Buffer` object I{GL_FLOAT}
    :arg buffer: Returns the feedback data.
 
 
@@ -592,7 +592,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    :type n: int
    :arg n: Specifies the number of textures name to be generated.
-   :type textures: :class:`Buffer` object I{type GL_INT}
+   :type textures: :class:`bgl.Buffer` object I{type GL_INT}
    :arg textures: Specifies an array in which the generated textures names are stored.
 
 
@@ -620,7 +620,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :arg plane: Specifies a clipping plane. The number of clipping planes depends on the
       implementation, but at least six clipping planes are supported. They are identified by
       symbolic names of the form GL_CLIP_PLANEi where 0 < i < GL_MAX_CLIP_PLANES.
-   :type equation:  :class:`Buffer` object I{type GL_FLOAT}
+   :type equation:  :class:`bgl.Buffer` object I{type GL_FLOAT}
    :arg equation:  Returns four float (double)-precision values that are the coefficients of the
       plane equation of plane in eye coordinates. The initial value is (0, 0, 0, 0).
 
@@ -646,7 +646,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
       names of the form GL_LIGHTi where 0 < i < GL_MAX_LIGHTS.
    :type pname: Enumerated constant
    :arg pname: Specifies a light source parameter for light.
-   :type params:  :class:`Buffer` object. Depends on function prototype.
+   :type params:  :class:`bgl.Buffer` object. Depends on function prototype.
    :arg params: Returns the requested data.
 
 
@@ -662,7 +662,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :arg target: Specifies the symbolic name of a map.
    :type query: Enumerated constant
    :arg query: Specifies which parameter to return.
-   :type v: :class:`Buffer` object. Depends on function prototype.
+   :type v: :class:`bgl.Buffer` object. Depends on function prototype.
    :arg v: Returns the requested data.
 
 
@@ -679,7 +679,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
       representing the front and back materials, respectively.
    :type pname: Enumerated constant
    :arg pname: Specifies the material parameter to return.
-   :type params: :class:`Buffer` object. Depends on function prototype.
+   :type params: :class:`bgl.Buffer` object. Depends on function prototype.
    :arg params: Returns the requested data.
 
 
@@ -693,7 +693,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    :type map:  Enumerated constant
    :arg map: Specifies the name of the pixel map to return.
-   :type values: :class:`Buffer` object. Depends on function prototype.
+   :type values: :class:`bgl.Buffer` object. Depends on function prototype.
    :arg values: Returns the pixel map contents.
 
 
@@ -703,7 +703,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    .. seealso:: `OpenGL Docs <http://www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/getpolygonstipple.html>`_
 
-   :type mask: :class:`Buffer` object I{type GL_BYTE}
+   :type mask: :class:`bgl.Buffer` object I{type GL_BYTE}
    :arg mask: Returns the stipple pattern. The initial value is all 1's.
 
 
@@ -730,7 +730,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :arg target: Specifies a texture environment. Must be GL_TEXTURE_ENV.
    :type pname: Enumerated constant
    :arg pname: Specifies the symbolic name of a texture environment parameter.
-   :type params: :class:`Buffer` object. Depends on function prototype.
+   :type params: :class:`bgl.Buffer` object. Depends on function prototype.
    :arg params: Returns the requested data.
 
 
@@ -746,7 +746,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :arg coord: Specifies a texture coordinate.
    :type pname: Enumerated constant
    :arg pname: Specifies the symbolic name of the value(s) to be returned.
-   :type params: :class:`Buffer` object. Depends on function prototype.
+   :type params: :class:`bgl.Buffer` object. Depends on function prototype.
    :arg params: Returns the requested data.
 
 
@@ -765,7 +765,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :arg format: Specifies a pixel format for the returned data.
    :type type: Enumerated constant
    :arg type: Specifies a pixel type for the returned data.
-   :type pixels: :class:`Buffer` object.
+   :type pixels: :class:`bgl.Buffer` object.
    :arg pixels: Returns the texture image. Should be a pointer to an array of the
       type specified by type
 
@@ -785,7 +785,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
       Level 0 is the base image level. Level n is the nth mipmap reduction image.
    :type pname: Enumerated constant
    :arg pname: Specifies the symbolic name of a texture parameter.
-   :type params: :class:`Buffer` object. Depends on function prototype.
+   :type params: :class:`bgl.Buffer` object. Depends on function prototype.
    :arg params: Returns the requested data.
 
 
@@ -801,7 +801,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :arg target: Specifies the symbolic name of the target texture.
    :type pname: Enumerated constant
    :arg pname: Specifies the symbolic name the target texture.
-   :type params: :class:`Buffer` object. Depends on function prototype.
+   :type params: :class:`bgl.Buffer` object. Depends on function prototype.
    :arg params: Returns the texture parameters.
 
 
@@ -826,7 +826,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    .. seealso:: `OpenGL Docs <http://www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/index_.html>`_
 
-   :type c: :class:`Buffer` object. Depends on function prototype.
+   :type c: :class:`bgl.Buffer` object. Depends on function prototype.
    :arg c: Specifies a pointer to a one element array that contains the new value for
       the current color index.
 
@@ -956,7 +956,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    .. seealso:: `OpenGL Docs <http://www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/loadmatrix.html>`_
 
-   :type m: :class:`Buffer` object. Depends on function prototype.
+   :type m: :class:`bgl.Buffer` object. Depends on function prototype.
    :arg m: Specifies a pointer to 16 consecutive values, which are used as the elements
       of a 4x4 column-major matrix.
 
@@ -1002,7 +1002,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
       occupy contiguous memory locations.
    :type order: int
    :arg order: Specifies the number of control points. Must be positive.
-   :type points: :class:`Buffer` object. Depends on function prototype.
+   :type points: :class:`bgl.Buffer` object. Depends on function prototype.
    :arg points: Specifies a pointer to the array of control points.
 
 
@@ -1043,7 +1043,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :type vorder: int
    :arg vorder: Specifies the dimension of the control point array in the v axis.
       Must be positive. The initial value is 1.
-   :type points: :class:`Buffer` object. Depends on function prototype.
+   :type points: :class:`bgl.Buffer` object. Depends on function prototype.
    :arg points: Specifies a pointer to the array of control points.
 
 
@@ -1103,7 +1103,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    .. seealso:: `OpenGL Docs <http://www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/multmatrix.html>`_
 
-   :type m: :class:`Buffer` object. Depends on function prototype.
+   :type m: :class:`bgl.Buffer` object. Depends on function prototype.
    :arg m: Points to 16 consecutive values that are used as the elements of a 4x4 column
       major matrix.
 
@@ -1132,7 +1132,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :type nx, ny, nz: Depends on function prototype. (non - 'v' prototypes only)
    :arg nx, ny, nz: Specify the x, y, and z coordinates of the new current normal.
       The initial value of the current normal is the unit vector, (0, 0, 1).
-   :type v: :class:`Buffer` object. Depends on function prototype. ('v' prototypes)
+   :type v: :class:`bgl.Buffer` object. Depends on function prototype. ('v' prototypes)
    :arg v: Specifies a pointer to an array of three elements: the x, y, and z coordinates
       of the new current normal.
 
@@ -1177,7 +1177,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :arg map: Specifies a symbolic map name.
    :type mapsize: int
    :arg mapsize: Specifies the size of the map being defined.
-   :type values: :class:`Buffer` object. Depends on function prototype.
+   :type values: :class:`bgl.Buffer` object. Depends on function prototype.
    :arg values: Specifies an array of mapsize values.
 
 
@@ -1266,7 +1266,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    .. seealso:: `OpenGL Docs <http://www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/polygonstipple.html>`_
 
-   :type mask: :class:`Buffer` object I{type GL_BYTE}
+   :type mask: :class:`bgl.Buffer` object I{type GL_BYTE}
    :arg mask: Specifies a pointer to a 32x32 stipple pattern that will be unpacked
       from memory in the same way that glDrawPixels unpacks pixels.
 
@@ -1307,9 +1307,9 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    :type n: int
    :arg n: Specifies the number of textures to be prioritized.
-   :type textures: :class:`Buffer` I{type GL_INT}
+   :type textures: :class:`bgl.Buffer` I{type GL_INT}
    :arg textures: Specifies an array containing the names of the textures to be prioritized.
-   :type priorities: :class:`Buffer` I{type GL_FLOAT}
+   :type priorities: :class:`bgl.Buffer` I{type GL_FLOAT}
    :arg priorities: Specifies an array containing the texture priorities.
       A priority given in an element of priorities applies to the texture named
       by the corresponding element of textures.
@@ -1417,7 +1417,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :arg format: Specifies the format of the pixel data.
    :type type: Enumerated constant
    :arg type: Specifies the data type of the pixel data.
-   :type pixels: :class:`Buffer` object
+   :type pixels: :class:`bgl.Buffer` object
    :arg pixels: Returns the pixel data.
 
 
@@ -1496,7 +1496,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    :type size: int
    :arg size: Specifies the size of buffer
-   :type buffer: :class:`Buffer` I{type GL_INT}
+   :type buffer: :class:`bgl.Buffer` I{type GL_INT}
    :arg buffer: Returns the selection data
 
 
@@ -1575,7 +1575,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :type s, t, r, q: Depends on function prototype. (r and q for '3' and '4' prototypes only)
    :arg s, t, r, q: Specify s, t, r, and q texture coordinates. Not all parameters are
       present in all forms of the command.
-   :type v: :class:`Buffer` object. Depends on function prototype. (for 'v' prototypes only)
+   :type v: :class:`bgl.Buffer` object. Depends on function prototype. (for 'v' prototypes only)
    :arg v: Specifies a pointer to an array of one, two, three, or four elements,
       which in turn specify the s, t, r, and q texture coordinates.
 
@@ -1642,7 +1642,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :arg format: Specifies the format of the pixel data.
    :type type: Enumerated constant
    :arg type: Specifies the data type of the pixel data.
-   :type pixels: :class:`Buffer` object.
+   :type pixels: :class:`bgl.Buffer` object.
    :arg pixels: Specifies a pointer to the image data in memory.
 
 
@@ -1673,7 +1673,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :arg format: Specifies the format of the pixel data.
    :type type: Enumerated constant
    :arg type: Specifies the data type of the pixel data.
-   :type pixels: :class:`Buffer` object.
+   :type pixels: :class:`bgl.Buffer` object.
    :arg pixels: Specifies a pointer to the image data in memory.
 
 
@@ -1720,7 +1720,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :type x, y, z, w: Depends on function prototype (z and w for '3' and '4' prototypes only)
    :arg x, y, z, w: Specify x, y, z, and w coordinates of a vertex. Not all parameters
       are present in all forms of the command.
-   :type v: :class:`Buffer` object. Depends of function prototype (for 'v'
+   :type v: :class:`bgl.Buffer` object. Depends of function prototype (for 'v'
       prototypes only)
    :arg v: Specifies a pointer to an array of two, three, or four elements. The
       elements of a two-element array are x and y; of a three-element array,
@@ -1795,7 +1795,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    :arg x, y: Specify the center of a picking region in window coordinates.
    :type width, height: double
    :arg width, height: Specify the width and height, respectively, of the picking region in window coordinates.
-   :type viewport: :class:`Buffer` object. [int]
+   :type viewport: :class:`bgl.Buffer` object. [int]
    :arg viewport: Specifies the current viewport.
 
 
@@ -1807,13 +1807,13 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    :type objx, objy, objz: double
    :arg objx, objy, objz: Specify the object coordinates.
-   :type modelMatrix: :class:`Buffer` object. [double]
+   :type modelMatrix: :class:`bgl.Buffer` object. [double]
    :arg modelMatrix: Specifies the current modelview matrix (as from a glGetDoublev call).
-   :type projMatrix: :class:`Buffer` object. [double]
+   :type projMatrix: :class:`bgl.Buffer` object. [double]
    :arg projMatrix: Specifies the current projection matrix (as from a glGetDoublev call).
-   :type viewport: :class:`Buffer` object. [int]
+   :type viewport: :class:`bgl.Buffer` object. [int]
    :arg viewport: Specifies the current viewport (as from a glGetIntegerv call).
-   :type winx, winy, winz: :class:`Buffer` object. [double]
+   :type winx, winy, winz: :class:`bgl.Buffer` object. [double]
    :arg winx, winy, winz: Return the computed window coordinates.
 
 
@@ -1825,13 +1825,13 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
 
    :type winx, winy, winz: double
    :arg winx, winy, winz: Specify the window coordinates to be mapped.
-   :type modelMatrix: :class:`Buffer` object. [double]
+   :type modelMatrix: :class:`bgl.Buffer` object. [double]
    :arg modelMatrix: Specifies the current modelview matrix (as from a glGetDoublev call).
-   :type projMatrix: :class:`Buffer` object. [double]
+   :type projMatrix: :class:`bgl.Buffer` object. [double]
    :arg projMatrix: Specifies the current projection matrix (as from a glGetDoublev call).
-   :type viewport: :class:`Buffer` object. [int]
+   :type viewport: :class:`bgl.Buffer` object. [int]
    :arg viewport: Specifies the current viewport (as from a glGetIntegerv call).
-   :type objx, objy, objz: :class:`Buffer` object. [double]
+   :type objx, objy, objz: :class:`bgl.Buffer` object. [double]
    :arg objx, objy, objz: Return the computed object coordinates.
 
 
diff --git a/doc/python_api/rst/gpu.rst b/doc/python_api/rst/gpu.rst
new file mode 100644
index 00000000000..72a5dc2f5d3
--- /dev/null
+++ b/doc/python_api/rst/gpu.rst
@@ -0,0 +1,531 @@
+
+GPU functions (gpu)
+===================
+
+*****
+Intro
+*****
+
+Module to provide functions concerning the GPU implementation in Blender, in particular
+the GLSL shaders that blender generates automatically to render materials in the 3D view
+and in the game engine.
+
+.. warning::
+
+    The API provided by this module should be consider unstable. The data exposed by the API 
+    are are closely related to Blender's internal GLSL code and may change if the GLSL code 
+    is modified (e.g. new uniform type). 
+
+.. module:: gpu
+
+*********
+Constants
+*********
+
+--------------
+GLSL data type
+--------------
+
+.. _data-type:
+
+Type of GLSL data.
+For shader uniforms, the data type determines which glUniform function
+variant to use to send the uniform value to the GPU.
+For vertex attributes, the data type determines which glVertexAttrib function
+variant to use to send the vertex attribute to the GPU.
+
+See export_shader_
+
+.. data:: GPU_DATA_1I
+
+   one integer
+
+   :value: 1
+
+.. data:: GPU_DATA_1F
+
+   one float
+
+   :value: 2
+
+.. data:: GPU_DATA_2F
+
+   two floats
+
+   :value: 3
+
+.. data:: GPU_DATA_3F
+
+   three floats
+   
+   :value: 4
+   
+.. data:: GPU_DATA_4F
+
+   four floats
+   
+   :value: 5
+   
+.. data:: GPU_DATA_9F
+
+   matrix 3x3 in column-major order
+
+   :value: 6
+
+.. data:: GPU_DATA_16F
+
+   matrix 4x4 in column-major order
+
+   :value: 7
+
+.. data:: GPU_DATA_4UB
+
+   four unsigned byte
+
+   :value: 8
+
+-----------------
+GLSL uniform type
+-----------------
+
+.. _uniform-type:
+
+Constants that specify the type of uniform used in a GLSL shader. 
+The uniform type determines the data type, origin and method
+of calculation used by Blender to compute the uniform value. 
+
+The calculation of some of the uniforms is based on matrices available in the scene:
+
+    .. _mat4_cam_to_world:
+    .. _mat4_world_to_cam:
+
+    *mat4_cam_to_world*
+      Model matrix of the camera. OpenGL 4x4 matrix that converts 
+      camera local coordinates to world coordinates. In blender this is obtained from the
+      'matrix_world' attribute of the camera object.
+
+      Some uniform will need the *mat4_world_to_cam*
+      matrix computed as the inverse of this matrix.
+
+    .. _mat4_object_to_world:
+    .. _mat4_world_to_object:
+
+    *mat4_object_to_world*
+      Model matrix of the object that is being rendered. OpenGL 4x4 matric that converts
+      object local coordinates to world coordinates. In blender this is obtained from the
+      'matrix_world' attribute of the object.
+  
+      Some uniform will need the *mat4_world_to_object* matrix, computed as the inverse of this matrix.
+  
+    .. _mat4_lamp_to_world:
+    .. _mat4_world_to_lamp:
+
+    *mat4_lamp_to_world*
+      Model matrix of the lamp lighting the object. OpenGL 4x4 matrix that converts lamp
+      local coordinates to world coordinates. In blender this is obtained from the
+      'matrix_world' attribute of the lamp object.
+      
+      Some uniform will need the *mat4_world_to_lamp* matrix
+      computed as the inverse of this matrix.
+
+.. data:: GPU_DYNAMIC_OBJECT_VIEWMAT
+
+    The uniform is a 4x4 GL matrix that converts world coordinates to 
+    camera coordinates (see mat4_world_to_cam_). Can be set once per frame.
+    There is at most one uniform of that type per shader.
+
+    :value: 1
+
+.. data:: GPU_DYNAMIC_OBJECT_MAT
+
+    The uniform is a 4x4 GL matrix that converts object coordinates 
+    to world coordinates (see mat4_object_to_world_). Must be set before drawing the object.
+    There is at most one uniform of that type per shader.
+
+    :value: 2
+
+.. data:: GPU_DYNAMIC_OBJECT_VIEWIMAT
+
+    The uniform is a 4x4 GL matrix that converts coordinates
+    in camera space to world coordinates (see mat4_cam_to_world_).
+    Can be set once per frame. 
+    There is at most one uniform of that type per shader.
+
+    :value: 3
+
+.. data:: GPU_DYNAMIC_OBJECT_IMAT
+
+    The uniform is a 4x4 GL matrix that converts world coodinates
+    to object coordinates (see mat4_world_to_object_).
+    Must be set before drawing the object.
+    There is at most one uniform of that type per shader.
+   
+    :value: 4
+   
+.. data:: GPU_DYNAMIC_OBJECT_COLOR
+
+    The uniform is a vector of 4 float representing a RGB color + alpha defined at object level.
+    Each values between 0.0 and 1.0. In blender it corresponds to the 'color' attribute of the object.
+    Must be set before drawing the object.
+    There is at most one uniform of that type per shader.
+   
+    :value: 5
+   
+.. data:: GPU_DYNAMIC_LAMP_DYNVEC
+
+    The uniform is a vector of 3 float representing the direction of light in camera space.
+    In Blender, this is computed by 
+
+    mat4_world_to_cam_ * (-vec3_lamp_Z_axis) 
+
+    as the lamp Z axis points to the opposite direction of light.
+    The norm of the vector should be unity. Can be set once per frame.
+    There is one uniform of that type per lamp lighting the material.
+
+    :value: 6
+   
+.. data:: GPU_DYNAMIC_LAMP_DYNCO
+
+    The uniform is a vector of 3 float representing the position of the light in camera space.
+    Computed as 
+    
+    mat4_world_to_cam_ * vec3_lamp_pos
+
+    Can be set once per frame.
+    There is one uniform of that type per lamp lighting the material.
+   
+    :value: 7
+   
+.. data:: GPU_DYNAMIC_LAMP_DYNIMAT
+
+    The uniform is a 4x4 GL matrix that converts vector in camera space to lamp space.
+    Computed as 
+
+    mat4_world_to_lamp_ * mat4_cam_to_world_
+
+    Can be set once per frame.
+    There is one uniform of that type per lamp lighting the material.
+
+    :value: 8
+
+.. data:: GPU_DYNAMIC_LAMP_DYNPERSMAT
+
+    The uniform is a 4x4 GL matrix that converts a vector in camera space to shadow buffer depth space.
+    Computed as 
+
+    mat4_perspective_to_depth_ * mat4_lamp_to_perspective_ * mat4_world_to_lamp_ * mat4_cam_to_world_.
+
+    .. _mat4_perspective_to_depth:
+
+    *mat4_perspective_to_depth* is a fixed matrix defined as follow::
+
+        0.5 0.0 0.0 0.5
+        0.0 0.5 0.0 0.5
+        0.0 0.0 0.5 0.5
+        0.0 0.0 0.0 1.0
+
+    This uniform can be set once per frame. There is one uniform of that type per lamp casting shadow in the scene.
+
+    :value: 9
+
+.. data:: GPU_DYNAMIC_LAMP_DYNENERGY
+
+    The uniform is a single float representing the lamp energy. In blender it corresponds
+    to the 'energy' attribute of the lamp data block.
+    There is one uniform of that type per lamp lighting the material.
+
+    :value: 10
+
+.. data:: GPU_DYNAMIC_LAMP_DYNCOL
+
+    The uniform is a vector of 3 float representing the lamp color. 
+    Color elements are between 0.0 and 1.0. In blender it corresponds
+    to the 'color' attribute of the lamp data block.
+    There is one uniform of that type per lamp lighting the material.
+
+    :value: 11
+
+.. data:: GPU_DYNAMIC_SAMPLER_2DBUFFER
+
+    The uniform is an integer representing an internal texture used for certain effect
+    (color band, etc). 
+	
+    :value: 12
+
+.. data:: GPU_DYNAMIC_SAMPLER_2DIMAGE
+
+    The uniform is an integer representing a texture loaded from an image file. 
+
+    :value: 13
+
+.. data:: GPU_DYNAMIC_SAMPLER_2DSHADOW
+
+    The uniform is an integer representing a shadow buffer corresponding to a lamp
+    casting shadow.
+
+    :value: 14
+
+-------------------
+GLSL attribute type
+-------------------
+
+.. _attribute-type:
+
+Type of the vertex attribute used in the GLSL shader. Determines the mesh custom data
+layer that contains the vertex attribute. 
+
+.. data:: CD_MTFACE
+
+    Vertex attribute is a UV layer. Data type is vector of 2 float.
+
+    There can be more than one attribute of that type, they are differenciated by name.
+    In blender, you can retrieve the attribute data with:
+
+    .. code-block:: python
+
+        mesh.uv_textures[attribute['name']]
+
+    :value: 5
+
+.. data:: CD_MCOL
+
+    Vertex attribute is color layer. Data type is vector 4 unsigned byte (RGBA).
+
+    There can be more than one attribute of that type, they are differenciated by name.
+    In blender you can retrieve the attribute data with:
+
+    .. code-block:: python
+
+        mesh.vertex_colors[attribute['name']]
+
+    :value: 6
+
+.. data:: CD_ORCO
+
+    Vertex attribute is original coordinates. Data type is vector 3 float.
+
+    There can be only 1 attribute of that type per shader.	
+    In blender you can retrieve the attribute data with:
+  
+    .. code-block:: python
+
+        mesh.vertices
+
+    :value: 14
+
+.. data:: CD_TANGENT
+
+    Vertex attribute is the tangent vector. Data type is vector 4 float.
+
+    There can be only 1 attribute of that type per shader.
+    There is currently no way to retrieve this attribute data via the RNA API but a standalone 
+    C function to compute the tangent layer from the other layers can be obtained from
+    blender.org.
+
+    :value: 18
+
+*********
+Functions
+*********
+
+.. _export_shader:
+
+.. function:: export_shader(scene,material)
+
+    Extracts the GLSL shader producing the visual effect of material in scene for the purpose of 
+    reusing the shader in an external engine. This function is meant to be used in material exporter 
+    so that the GLSL shader can be exported entirely. The return value is a dictionary containing the
+    shader source code and all associated data. 
+
+    :arg scene: the scene in which the material in rendered.
+    :type scene: :class:`bpy.types.Scene`
+    :arg material: the material that you want to export the GLSL shader
+    :type material: :class:`bpy.types.Material`
+    :return: the shader source code and all associated data in a dictionary
+    :rtype: dictionary
+
+    The dictionary contains the following elements:
+
+    * ['fragment'] : string
+        fragment shader source code.
+    
+    * ['vertex'] : string
+        vertex shader source code.
+
+    * ['uniforms'] : sequence
+        list of uniforms used in fragment shader, can be empty list. Each element of the
+        sequence is a dictionary with the following elements:
+
+        * ['varname'] : string
+            name of the uniform in the fragment shader. Always of the form 'unf<number>'.
+
+        * ['datatype'] : integer
+            data type of the uniform variable. Can be one of the following:
+
+            * :data:`gpu.GPU_DATA_1I` : use glUniform1i
+            * :data:`gpu.GPU_DATA_1F` : use glUniform1fv
+            * :data:`gpu.GPU_DATA_2F` : use glUniform2fv
+            * :data:`gpu.GPU_DATA_3F` : use glUniform3fv
+            * :data:`gpu.GPU_DATA_4F` : use glUniform4fv
+            * :data:`gpu.GPU_DATA_9F` : use glUniformMatrix3fv
+            * :data:`gpu.GPU_DATA_16F` : use glUniformMatrix4fv
+
+        * ['type'] : integer
+            type of uniform, determines the origin and method of calculation. See uniform-type_.
+            Depending on the type, more elements will be be present.
+
+        * ['lamp'] : :class:`bpy.types.Object`
+            Reference to the lamp object from which the uniforms value are extracted. Set for the following uniforms types:
+
+            .. hlist::
+               :columns: 3
+
+               * :data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC`
+               * :data:`gpu.GPU_DYNAMIC_LAMP_DYNCO`
+               * :data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT`
+               * :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT`
+               * :data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY`
+               * :data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL`
+               * :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`
+
+            Notes:
+
+            * The uniforms :data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC`, :data:`gpu.GPU_DYNAMIC_LAMP_DYNCO`, :data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT` and :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT`
+              refer to the lamp object position and orientation, both of can be derived from the object world matrix:
+
+              .. code-block:: python
+
+                obmat = uniform['lamp'].matrix_world
+
+              where obmat is the mat4_lamp_to_world_ matrix of the lamp as a 2 dimensional array,
+              the lamp world location location is in obmat[3].
+
+            * The uniform types :data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY` and :data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL` refer to the lamp data bloc that you get from:
+
+              .. code-block:: python
+
+                la = uniform['lamp'].data
+          
+              from which you get la.energy and la.color
+
+            * Lamp duplication is not supported: if you have duplicated lamps in your scene
+              (i.e. lamp that are instantiated by dupligroup, etc), this element will only 
+              give you a reference to the orignal lamp and you will not know which instance
+              of the lamp it is refering too. You can still handle that case in the exporter
+              by distributing the uniforms amongst the duplicated lamps.
+              
+        * ['image'] : :class:`bpy.types.Image`
+            Reference to the image databloc. Set for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE`. You can get the image data from:
+
+            .. code-block:: python
+
+               # full path to image file
+               uniform['image'].filepath
+               # image size as a 2-dimensional array of int
+               uniform['image'].size
+
+        * ['texnumber'] : integer
+            Channel number to which the texture is bound when drawing the object.
+            Set for uniform types :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`, :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE` and :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`.
+
+            This is provided for information only: when reusing the shader outside blencer, 
+            you are free to assign the textures to the channel of your choice and to pass
+            that number channel to the GPU in the uniform.
+
+        * ['texpixels'] : byte array
+            texture data for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`. Although
+            the corresponding uniform is a 2D sampler, the texture is always a 1D texture
+            of n x 1 pixel. The texture size n is provided in ['texsize'] element. 
+            These texture are only used for computer generated texture (colorband, etc).
+            The texture data is provided so that you can make a real image out of it in the
+            exporter.
+		
+        * ['texsize'] : integer
+            horizontal size of texture for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`. 
+            The texture data is in ['texpixels'].
+
+    * ['attributes'] : sequence
+        list of attributes used in vertex shader, can be empty. Blender doesn't use
+        standard attributes except for vertex position and normal. All other vertex
+        attributes must be passed using the generic glVertexAttrib functions.
+        The attribute data can be found in the derived mesh custom data using RNA.
+        Each element of the sequence is a dictionary containing the following elements:
+
+        * ['varname'] : string
+            name of the uniform in the vertex shader. Always of the form 'att<number>'.
+
+        * ['datatype'] : integer
+            data type of vertex attribute, can be one of the following:
+
+            * :data:`gpu.GPU_DATA_2F` : use glVertexAttrib2fv
+            * :data:`gpu.GPU_DATA_3F` : use glVertexAttrib3fv
+            * :data:`gpu.GPU_DATA_4F` : use glVertexAttrib4fv
+            * :data:`gpu.GPU_DATA_4UB` : use glVertexAttrib4ubv
+
+        * ['number'] : integer
+            generic attribute number. This is provided for information only. Blender 
+            doesn't use glBindAttribLocation to place generic attributes at specific location,
+            it lets the shader compiler place the attributes automatically and query the 
+            placement with glGetAttribLocation. The result of this placement is returned in 
+            this element. 
+
+            When using this shader in a render engine, you should either use
+            glBindAttribLocation to force the attribute at this location or use 
+            glGetAttribLocation to get the placement chosen by the compiler of your GPU.
+
+        * ['type'] : integer
+            type of the mesh custom data from which the vertex attribute is loaded. 
+            See attribute-type_.
+
+        * ['name'] : string or integer
+            custom data layer name, used for attribute type :data:`gpu.CD_MTFACE` and :data:`gpu.CD_MCOL`.
+
+    Example:
+
+    .. code-block:: python
+
+        import gpu
+        # get GLSL shader of material Mat.001 in scene Scene.001
+        scene = bpy.data.scenes['Scene.001']
+        material = bpy.data.materials['Mat.001']
+        shader = gpu.export_shader(scene,material)
+        # scan the uniform list and find the images used in the shader
+        for uniform in shader['uniforms']:
+            if uniform['type'] == gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE:
+                print("uniform {0} is using image {1}".format(uniform['varname'], uniform['image'].filepath))
+        # scan the attribute list and find the UV layer used in the shader
+        for attribute in shader['attributes']:
+            if attribute['type'] == gpu.CD_MTFACE:
+                print("attribute {0} is using UV layer {1}".format(attribute['varname'], attribute['name']))
+
+*****
+Notes
+*****
+
+.. _mat4_lamp_to_perspective:
+
+1. Calculation of the *mat4_lamp_to_perspective* matrix for a spot lamp.
+
+   The following pseudo code shows how the *mat4_lamp_to_perspective* matrix is computed 
+   in blender for uniforms of :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT` type::
+
+     #Get the lamp datablock with:
+     lamp=bpy.data.objects[uniform['lamp']].data
+
+     #Compute the projection matrix:
+     #  You will need these lamp attributes:
+     #  lamp.clipsta : near clip plane in world unit
+     #  lamp.clipend : far clip plane in world unit
+     #  lamp.spotsize : angle in degree of the spot light
+
+     #The size of the projection plane is computed with the usual formula:
+     wsize = lamp.clista * tan(lamp.spotsize/2)
+
+     #And the projection matrix:
+     mat4_lamp_to_perspective = glFrustum(-wsize,wsize,-wsize,wsize,lamp.clista,lamp.clipend)
+
+2. Creation of the shadow map for a spot lamp.
+
+   The shadow map is the depth buffer of a render performed by placing the camera at the
+   spot light position. The size of the shadow map is given by the attribute lamp.bufsize : 
+   shadow map size in pixel, same size in both dimensions.
diff --git a/doc/python_api/rst/info_best_practice.rst b/doc/python_api/rst/info_best_practice.rst
new file mode 100644
index 00000000000..2fbc636613c
--- /dev/null
+++ b/doc/python_api/rst/info_best_practice.rst
@@ -0,0 +1,65 @@
+*************
+Best Practice
+*************
+
+
+TODO: Intro text
+
+
+Style Conventions
+=================
+
+For Blender 2.5 we have chosen to follow python suggested style guide to avoid mixing styles amongst our own scripts and make it easier to use python scripts from other projects.
+
+Using our style guide for your own scripts makes it easier if you eventually want to contribute them to blender.
+
+This style guide is known as pep8 and can be found `here <http://www.python.org/dev/peps/pep-0008>`_
+
+A brief listing of pep8 criteria.
+
+* camel caps for class names: MyClass
+
+* all lower case underscore separated module names: my_module
+
+* indentation of 4 spaces (no tabs)
+
+* spaces around operators. ``1 + 1``, not ``1+1``
+
+* only use explicit imports, (no importing '*')
+
+* don't use single line: ``if val: body``, separate onto 2 lines instead.
+
+
+As well as pep8 we have other conventions used for blender python scripts.
+
+* Use single quotes for enums, and double quotes for strings.
+
+  Both are of course strings but in our internal API enums are unique items from a limited set. eg.
+
+  .. code-block:: python
+
+     bpy.context.scene.render.file_format = 'PNG'
+     bpy.context.scene.render.filepath = "//render_out"
+
+* pep8 also defines that lines should not exceed 79 characters, we felt this is too restrictive so this is optional per script.
+
+Periodically we run checks for pep8 compliance on blender scripts, for scripts to be included in this check add this line as a comment at the top of the script.
+
+``# <pep8 compliant>``
+
+To enable line length checks use this instead.
+
+``# <pep8-80 compliant>``
+
+
+User Interface Layout
+=====================
+
+TODO: Thomas
+
+
+Script Efficiency
+=================
+
+TODO: Campbell
+
diff --git a/doc/python_api/rst/info_quickstart.rst b/doc/python_api/rst/info_quickstart.rst
index e77e9a76d7f..e7f2900b212 100644
--- a/doc/python_api/rst/info_quickstart.rst
+++ b/doc/python_api/rst/info_quickstart.rst
@@ -156,7 +156,7 @@ Note that these properties can only be assigned  basic Python types.
 
 * array of ints/floats
 
-* dictionary (only string keys types on this list)
+* dictionary (only string keys are supported, values must be basic types too)
 
 These properties are valid outside of Python. They can be animated by curves or used in driver paths.
 
@@ -420,49 +420,3 @@ Using Low-Level Functions:
    fcu_z.keyframe_points[0].co = 10.0, 0.0
    fcu_z.keyframe_points[1].co = 20.0, 1.0
 
-
-Style Conventions
-=================
-
-For Blender 2.5 we have chosen to follow python suggested style guide to avoid mixing styles amongst our own scripts and make it easier to use python scripts from other projects.
-
-Using our style guide for your own scripts makes it easier if you eventually want to contribute them to blender.
-
-This style guide is known as pep8 and can be found `here <http://www.python.org/dev/peps/pep-0008>`_
-
-A brief listing of pep8 criteria.
-
-* camel caps for class names: MyClass
-
-* all lower case underscore separated module names: my_module
-
-* indentation of 4 spaces (no tabs)
-
-* spaces around operators. ``1 + 1``, not ``1+1``
-
-* only use explicit imports, (no importing '*')
-
-* don't use single line: ``if val: body``, separate onto 2 lines instead.
-
-
-As well as pep8 we have other conventions used for blender python scripts.
-
-* Use single quotes for enums, and double quotes for strings.
-
-  Both are of course strings but in our internal API enums are unique items from a limited set. eg.
-
-  .. code-block:: python
-
-     bpy.context.scene.render.file_format = 'PNG'
-     bpy.context.scene.render.filepath = "//render_out"
-
-* pep8 also defines that lines should not exceed 79 characters, we felt this is too restrictive so this is optional per script.
-
-Periodically we run checks for pep8 compliance on blender scripts, for scripts to be included in this check add this line as a comment at the top of the script.
-
-``# <pep8 compliant>``
-
-To enable line length checks use this instead.
-
-``# <pep8-80 compliant>``
-
diff --git a/doc/python_api/rst/info_tips_and_tricks.rst b/doc/python_api/rst/info_tips_and_tricks.rst
index bd5faf000c8..bd3ed196193 100644
--- a/doc/python_api/rst/info_tips_and_tricks.rst
+++ b/doc/python_api/rst/info_tips_and_tricks.rst
@@ -1,57 +1,228 @@
-###############
+***************
 Tips and Tricks
-###############
+***************
 
-Some of these are just python features that scripters may not have thaught to use with blender.
+Here are various suggestions that you might find useful when writing scripts.
+
+Some of these are just python features that scripters may not have thought to use with blender, others are blender specific.
 
 
-****************
 Use The Terminal
-****************
+================
+
+When writing python scripts, its useful to have a terminal open, this is not the built-in python console but a terminal application which is used to start blender.
+
+There are 3 main uses for the terminal, these are:
+
+* You can see the output of `print()` as you're script runs, which is useful to view debug info.
+
+* The error trace-back is printed in full to the terminal which wont always generate an error popup in blenders user interface (depending on how the script is executed).
+
+* If the script runs for too long or you accidentally enter an infinite loop, Ctrl+C in the terminal (Ctrl+Break on Windows) will quit the script early.
+
+.. note::
+   For Linux and OSX users this means starting the terminal first, then running blender from within it. On Windows the terminal can be enabled from the help menu.
+
+
+Use an External Editor
+======================
+
+Blenders text editor is fine for small changes and writing tests but its not full featured, for larger projects you'll probably want to use a standalone editor or python IDE.
+
+Editing a text file externally and having the same text open in blender does work but isn't that optimal so here are 2 ways you can easily use an external file from blender.
+
+Using the following examples you'll still need textblock in blender to execute, but reference an external file rather then including it directly.
+
+Executing External Scripts
+--------------------------
+
+This is the equivalent to running the script directly, referencing a scripts path from a 2 line textblock.
+
+.. code-block:: python
+
+   filename = "/full/path/to/myscript.py"
+   exec(compile(open(filename).read(), filename, 'exec'))
+
+
+You might want to reference a script relative to the blend file.
+
+.. code-block:: python
+
+   import bpy
+   import os
+
+   filename = os.path.join(os.path.basename(bpy.data.filepath), "myscript.py")
+   exec(compile(open(filename).read(), filename, 'exec'))
+
 
-For Linux and OSX users this means starting the terminal first, then running blender from within it. on Windows the terminal can be enabled from the help menu.
+Executing Modules
+-----------------
 
-********************
-Run External Scripts
-********************
+This example shows loading a script in as a module and executing a module function.
+
+.. code-block:: python
+
+   import myscript
+   import imp
+
+   imp.reload(myscript)
+   myscript.main()
+
+
+Notice that the script is reloaded every time, this forces use of the modified version otherwise the cached one in `sys.modules` would be used until blender was restarted.
+
+The important difference between this and executing the script directly is it has to call a function in the module, in this case `main()` but it can be any function, an advantage with this is you can pass arguments to the function from this small script which is often useful for testing different settings quickly.
+
+The other issue with this is the script has to be in pythons module search path.
+While this is not best practice - for testing you can extend the search path, this example adds the current blend files directory to the search path, then loads the script as a module.
+
+.. code-block:: python
+
+   import sys
+   import os
+   import bpy
+
+   blend_dir = os.path.basename(bpy.data.filepath)
+   if blend_dir not in sys.path:
+      sys.path.append(blend_dir)
+
+   import myscript
+   import imp
+   imp.reload(myscript)
+   myscript.main()
 
 
-******************
 Don't Use Blender!
-******************
+==================
+
+While developing your own scripts blenders interface can get in the way, manually reloading, running the scripts, opening file import etc. adds overhead.
+
+For scripts that are not interactive it can end up being more efficient not to use blenders interface at all and instead execute the script on the command line.
+
+.. code-block:: python
+
+   blender --background --python myscript.py
+
+
+You might want to run this with a blend file so the script has some data to operate on.
+
+.. code-block:: python
+
+   blender myscene.blend --background --python myscript.py
+
+
+.. note::
+
+   Depending on you're setup you might have to enter the full path to the blender executable.
+
+
+Once the script is running properly in background mode, you'll want to check the output of the script, this depends completely on the task at hand however here are some suggestions.
+
+* render the output to an image, use an image viewer and keep writing over the same image each time.
+
+* save a new blend file, or export the file using one of blenders exporters.
+
+* if the results can be displayed as text - print them or write them to a file.
+
+
+This can take a little time to setup, but it can be well worth the effort to reduce the time it takes to test changes - you can even have blender running the script ever few seconds with a viewer updating the results, so no need to leave you're text editor to see changes.
 
 
-******************
 Use External Tools
-******************
+==================
+
+When there are no readily available python modules to perform specific tasks its worth keeping in mind you may be able to have python execute an external command on you're data and read the result back in.
+
+Using external programs adds an extra dependency and may limit who can use the script but to quickly setup you're own custom pipeline or writing one-off scripts this can be handy.
+
+Examples include:
+
+* Run The Gimp in batch mode to execute custom scripts for advanced image processing.
 
+* Write out 3D models to use external mesh manipulation tools and read back in the results.
 
-**************
-Bundled Python
-**************
+* Convert files into recognizable formats before reading.
 
-Blender from blender.org includes a compleate python installation on all platforms, this has the disadvantage that any extensions you have installed in you're systems python wont be found by blender.
+
+Bundled Python & Extensions
+===========================
+
+The Blender releases distributed from blender.org include a complete python installation on all platforms, this has the disadvantage that any extensions you have installed in you're systems python wont be found by blender.
 
 There are 2 ways around this:
 
-* remove blender python subdirectory, blender will then look for the systems python and use that instead **python version must match the one that blender comes with**.
+* remove blender python sub-directory, blender will then fallback on the systems python and use that instead **python version must match the one that blender comes with**.
+
+* copy the extensions into blender's python sub-directory so blender can access them, you could also copy the entire python installation into blenders sub-directory, replacing the one blender comes with. This works as long as the python versions match and the paths are created in the same relative locations. Doing this has the advantage that you can redistribute this bundle to others with blender and/or the game player, including any extensions you rely on.
+
+
+Drop Into a Python Interpreter in You're Script
+===============================================
+
+In the middle of a script you may want to inspect some variables, run some function and generally dig about to see whats going on.
+
+.. code-block:: python
+
+   import code
+   code.interact(local=locals())
+
+
+If you want to access both global and local variables do this...
+
+.. code-block:: python
+
+   import code
+   namespace = globals().copy()
+   namespace.update(locals())
+   code.interact(local=namespace)
+
+
+The next example is an equivalent single line version of the script above which is easier to paste into you're code:
+
+.. code-block:: python
+
+   __import__('code').interact(local={k: v for ns in (globals(), locals()) for k, v in ns.items()})
+
+
+`code.interact` can be added at any line in the script and will pause the script an launch an interactive interpreter in the terminal, when you're done you can quit the interpreter and the script will continue execution.
+
+
+Admittedly this highlights the lack of any python debugging support built into blender, but its still handy to know.
+
+.. note::
+
+   This works in the game engine as well, it can be handy to inspect the state of a running game.
 
-* copy the extensions into blender's python subdirectry so blender can access them, you could also copy the entire python installation into blenders subdirectory, replacing the one blender comes with. This works as long as the python versions match and the paths are created in the same location relative locations. Doing this has the advantage that you can redistribute this bundle to others with blender and/or the game player, including any extensions you rely on.
 
-********
 Advanced
-********
+========
 
 
-===================
 Blender as a module
-===================
+-------------------
+
+From a python perspective its nicer to have everything as an extension which lets the python script combine many components.
+
+Advantages include:
+
+* you can use external editors/IDE's with blenders python API and execute scripts within the IDE (step over code, inspect variables as the script runs).
+
+* editors/IDE's can auto complete blender modules & variables.
+
+* existing scripts can import blender API's without having to run inside blender.
+
+
+This is marked advanced because to run blender as a python module requires a special build option.
+
+For instructions on building see `Building blender as a python module <http://wiki.blender.org/index.php/User:Ideasman42/BlenderAsPyModule>`_
 
 
-============================
 Python Safety (Build Option)
-============================
+----------------------------
+
+Since its possible to accessed data which has been removed (see Gotcha's), this can be a hard to track down the cause of crashes.
+
+To raise python exceptions on accessing freed data (rather then crashing), enable the CMake build option WITH_PYTHON_SAFETY.
+
+This enables data tracking which makes data access about 2x slower which is why the option is not enabled in release builds.
 
-=================
-CTypes in Blender
-=================
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py
index 787d6d69118..df17c54b55f 100644
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@@ -104,6 +104,8 @@ sphinx-build doc/python_api/sphinx-in doc/python_api/sphinx-out
 INFO_DOCS = (
     ("info_quickstart.rst", "Blender/Python Quickstart: new to blender/scripting and want to get you're feet wet?"),
     ("info_overview.rst", "Blender/Python API Overview: a more complete explanation of python integration"),
+    ("info_best_practice.rst", "Best Practice: Conventions to follow for writing good scripts"),
+    ("info_tips_and_tricks.rst", "Tips and Tricks: Hints to help you while writeing scripts for blender"),
     ("info_gotcha.rst", "Gotcha's: some of the problems you may come up against when writing scripts"),
     )
 
@@ -586,6 +588,7 @@ def pycontext2sphinx(BASEPATH):
         "sequences": ("Sequence", True),
         "smoke": ("SmokeModifier", False),
         "soft_body": ("SoftBodyModifier", False),
+        "speaker": ("Speaker", False),
         "texture": ("Texture", False),
         "texture_slot": ("MaterialTextureSlot", False),
         "vertex_paint_object": ("Object", False),