sphinx doc gen: multiple examples possible and include the scripts docstring inline in sphinx.

also tag unused vars

doc/python_api/examples/bpy.types.Operator.1.py

@@ -0,0 +1,43 @@
+"""
+Invoke Function
++++++++++++++++
+This example shows how to define an operator which gets mouse input to
+execute a function and that this operator can be invoked or executed from
+the python api.
+
+Also notice this operator defines its own properties, these are different
+to typical class properties because blender registers them with the
+operator, to use as arguments when called, saved for operator undo/redo and
+automatically added into the user interface.
+"""
+import bpy
+
+
+class SimpleMouseOperator(bpy.types.Operator):
+    """This operator shows the mouse location, this string is used for the tooltip and API docs"""
+    bl_idname = "wm.mouse_position"
+    bl_label = "Invoke Mouse Operator"
+
+    x = bpy.props.IntProperty()
+    y = bpy.props.IntProperty()
+
+    def execute(self, context):
+        # rather then printing, use the report function,
+        # this way the messag appiers in the header,
+        self.report({'INFO'}, "Mouse coords are %d %d" % (self.x, self.y))
+        return {'FINISHED'}
+
+    def invoke(self, context, event):
+        self.x = event.mouse_x
+        self.y = event.mouse_y
+        return self.execute(context)
+
+bpy.utils.register_class(SimpleMouseOperator)
+
+# Test call to the newly defined operator.
+# Here we call the operator and invoke it, meaning that the settings are taken
+# from the mouse.
+bpy.ops.wm.mouse_position('INVOKE_DEFAULT')
+
+# Another test call, this time call execute() directly with pre-defined settings.
+bpy.ops.wm.mouse_position('EXEC_DEFAULT', x=20, y=66)

doc/python_api/examples/bpy.types.Operator.2.py

@@ -0,0 +1,36 @@
+"""
+Calling a File Selector
++++++++++++++++++++++++
+This example shows how an operator can use the file selector
+"""
+import bpy
+
+
+class ExportSomeData(bpy.types.Operator):
+    """Test exporter which just writes hello world"""
+    bl_idname = "export.some_data"
+    bl_label = "Export Some Data"
+
+    filepath = bpy.props.StringProperty(subtype="FILE_PATH")
+
+    def execute(self, context):
+        file = open(self.filepath, 'w')
+        file.write("Hello World")
+        return {'FINISHED'}
+
+    def invoke(self, context, event):
+        context.window_manager.fileselect_add(self)
+        return {'RUNNING_MODAL'}
+
+
+# Only needed if you want to add into a dynamic menu
+def menu_func(self, context):
+    self.layout.operator(ExportSomeData.bl_idname, text="Text Export Operator")
+
+# Register and add to the file selector
+bpy.utils.register_class(ExportSomeData)
+bpy.types.INFO_MT_file_export.append(menu_func)
+
+
+# test call
+bpy.ops.export.some_data('INVOKE_DEFAULT')

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

@@ -0,0 +1,20 @@
+"""
+Basic Operator Example
+++++++++++++++++++++++
+This script is the most simple operator you can write that does something.
+"""
+import bpy
+
+
+class HelloWorldOperator(bpy.types.Operator):
+    bl_idname = "wm.hello_world"
+    bl_label = "Minimal Operator"
+
+    def execute(self, context):
+        print("Hello World")
+        return {'FINISHED'}
+
+bpy.utils.register_class(SimpleOperator)
+
+# test call to the newly defined operator
+bpy.ops.wm.hello_world()