From aed7eaf0d9171c4bfa7814e141afad773cb31441 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Wed, 16 Feb 2011 17:31:04 +0000 Subject: 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 | 43 ++++++++++++++++++ doc/python_api/examples/bpy.types.Operator.2.py | 36 +++++++++++++++ doc/python_api/examples/bpy.types.Operator.py | 20 +++++++++ doc/python_api/sphinx_doc_gen.py | 52 +++++++++++++++++++++- source/blender/editors/armature/poselib.c | 4 +- .../blender/modifiers/intern/MOD_particlesystem.c | 3 +- 6 files changed, 152 insertions(+), 6 deletions(-) create mode 100644 doc/python_api/examples/bpy.types.Operator.1.py create mode 100644 doc/python_api/examples/bpy.types.Operator.2.py create mode 100644 doc/python_api/examples/bpy.types.Operator.py diff --git a/doc/python_api/examples/bpy.types.Operator.1.py b/doc/python_api/examples/bpy.types.Operator.1.py new file mode 100644 index 00000000000..03a3f6d70d6 --- /dev/null +++ b/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) diff --git a/doc/python_api/examples/bpy.types.Operator.2.py b/doc/python_api/examples/bpy.types.Operator.2.py new file mode 100644 index 00000000000..1673b22fbf1 --- /dev/null +++ b/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') diff --git a/doc/python_api/examples/bpy.types.Operator.py b/doc/python_api/examples/bpy.types.Operator.py new file mode 100644 index 00000000000..2efa99ce795 --- /dev/null +++ b/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() diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index 565a6447cc8..38218675484 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -73,7 +73,7 @@ else: "mathutils.geometry", ) - FILTER_BPY_TYPES = ("Mesh", ) # allow + FILTER_BPY_TYPES = ("Operator", ) # allow FILTER_BPY_OPS = ("import_scene", ) # allow # for quick rebuilds @@ -131,14 +131,60 @@ def range_str(val): return str(val) +def example_extract_docstring(filepath): + file = open(filepath, 'r') + line = file.readline() + line_no = 0 + text = [] + if line.startswith('"""'): # assume nothing here + line_no += 1 + else: + file.close() + return "", 0 + + for line in file.readlines(): + line_no += 1 + if line.startswith('"""'): + break + else: + text.append(line.rstrip()) + + line_no += 1 + file.close() + return "\n".join(text), line_no + + def write_example_ref(ident, fw, example_id, ext="py"): if example_id in EXAMPLE_SET: - fw("%s.. literalinclude:: ../examples/%s.%s\n\n" % (ident, example_id, ext)) + + # extract the comment + filepath = "../examples/%s.%s" % (example_id, ext) + filepath_full = os.path.join(os.path.dirname(fw.__self__.name), filepath) + + text, line_no = example_extract_docstring(filepath_full) + + for line in text.split("\n"): + fw("%s\n" % (ident + line).rstrip()) + fw("\n") + + fw("%s.. literalinclude:: %s\n" % (ident, filepath)) + fw("%s :lines: %d-\n" % (ident, line_no)) + fw("\n") EXAMPLE_SET_USED.add(example_id) else: if bpy.app.debug: print("\tskipping example:", example_id) + # Support for numbered files bpy.types.Operator -> bpy.types.Operator.1.py + i = 1 + while True: + example_id_num = "%s.%d" % (example_id, i) + if example_id_num in EXAMPLE_SET: + write_example_ref(ident, fw, example_id_num, ext) + i += 1 + else: + break + def write_indented_lines(ident, fn, text, strip=True): ''' @@ -517,6 +563,8 @@ def pyrna2sphinx(BASEPATH): fw(".. module:: bpy.types\n\n") + write_example_ref("", fw, "bpy.types.%s" % struct.identifier) + base_ids = [base.identifier for base in struct.get_bases()] if _BPY_STRUCT_FAKE: diff --git a/source/blender/editors/armature/poselib.c b/source/blender/editors/armature/poselib.c index 7e27cfbe0e1..bfe33299043 100644 --- a/source/blender/editors/armature/poselib.c +++ b/source/blender/editors/armature/poselib.c @@ -189,7 +189,7 @@ static bAction *poselib_validate (Object *ob) /* ************************************************************* */ /* Pose Lib UI Operators */ -static int poselib_new_exec (bContext *C, wmOperator *op) +static int poselib_new_exec (bContext *C, wmOperator *UNUSED(op)) { Object *ob = get_poselib_object(C); @@ -223,7 +223,7 @@ void POSELIB_OT_new (wmOperatorType *ot) /* ------------------------------------------------ */ -static int poselib_unlink_exec (bContext *C, wmOperator *op) +static int poselib_unlink_exec (bContext *C, wmOperator *UNUSED(op)) { Object *ob = get_poselib_object(C); diff --git a/source/blender/modifiers/intern/MOD_particlesystem.c b/source/blender/modifiers/intern/MOD_particlesystem.c index 246a1b5391e..2f3bc0c53f4 100644 --- a/source/blender/modifiers/intern/MOD_particlesystem.c +++ b/source/blender/modifiers/intern/MOD_particlesystem.c @@ -80,11 +80,10 @@ static void copyData(ModifierData *md, ModifierData *target) tpsmd->psys = psmd->psys; } -static CustomDataMask requiredDataMask(Object *ob, ModifierData *md) +static CustomDataMask requiredDataMask(Object *UNUSED(ob), ModifierData *md) { ParticleSystemModifierData *psmd= (ParticleSystemModifierData*) md; CustomDataMask dataMask = 0; - Material *ma; MTex *mtex; int i; -- cgit v1.2.3