diff options
author | Campbell Barton <ideasman42@gmail.com> | 2011-03-22 07:28:51 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2011-03-22 07:28:51 +0300 |
commit | 1b80538fea5b42f5b3111066f617d94a4ffc180c (patch) | |
tree | 68cbdb095a32dc28b0c76341132946f6e768690a | |
parent | 3384679aecfe93ae72bd34eb9b17095db2603eb2 (diff) |
fix [#25688] undocumted functions in pyapi
expose collection function docs.
-rw-r--r-- | doc/python_api/sphinx_doc_gen.py | 75 | ||||
-rw-r--r-- | release/scripts/modules/rna_info.py | 6 | ||||
-rw-r--r-- | source/blender/editors/transform/transform_manipulator.c | 9 | ||||
-rw-r--r-- | source/blender/python/intern/bpy_rna.c | 42 |
4 files changed, 94 insertions, 38 deletions
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index e51ea516158..bc190231e36 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -36,7 +36,7 @@ For HTML generation sphinx-build doc/python_api/sphinx-in doc/python_api/sphinx-out - assuming that you have sphinx 0.6.7 installed + assuming that you have sphinx 1.0.7 installed For PDF generation ------------------ @@ -61,7 +61,7 @@ else: "bpy.app", "bpy.path", "bpy.data", - #"bpy.props", + "bpy.props", "bpy.utils", "bpy.context", # "bpy.types", # supports filtering @@ -102,8 +102,13 @@ EXAMPLE_SET = set() EXAMPLE_SET_USED = set() _BPY_STRUCT_FAKE = "bpy_struct" +_BPY_PROP_COLLECTION_FAKE = "bpy_prop_collection" _BPY_FULL_REBUILD = False +if _BPY_PROP_COLLECTION_FAKE: + _BPY_PROP_COLLECTION_ID = ":class:`%s`" % _BPY_PROP_COLLECTION_FAKE +else: + _BPY_PROP_COLLECTION_ID = "collection" def undocumented_message(module_name, type_name, identifier): if str(type_name).startswith('<module'): @@ -155,6 +160,10 @@ def example_extract_docstring(filepath): return "\n".join(text), line_no +def write_title(fw, text, heading_char): + fw("%s\n%s\n\n" % (text, len(text) * heading_char)) + + def write_example_ref(ident, fw, example_id, ext="py"): if example_id in EXAMPLE_SET: @@ -310,8 +319,7 @@ def pymodule2sphinx(BASEPATH, module_name, module, title): fw = file.write - fw(title + "\n") - fw(("=" * len(title)) + "\n\n") + write_title(fw, title, "=") fw(".. module:: %s\n\n" % module_name) @@ -535,14 +543,18 @@ def pyrna2sphinx(BASEPATH): if is_return: id_name = "return" id_type = "rtype" - kwargs = {"as_ret": True, "class_fmt": ":class:`%s`"} + kwargs = {"as_ret": True} identifier = "" else: id_name = "arg" id_type = "type" - kwargs = {"as_arg": True, "class_fmt": ":class:`%s`"} + kwargs = {"as_arg": True} identifier = " %s" % prop.identifier + kwargs["class_fmt"] = ":class:`%s`" + + kwargs["collection_id"] = _BPY_PROP_COLLECTION_ID + type_descr = prop.get_type_description(**kwargs) if prop.name or prop.description: fw(ident + ":%s%s: %s\n" % (id_name, identifier, ", ".join(val for val in (prop.name, prop.description) if val))) @@ -570,7 +582,7 @@ def pyrna2sphinx(BASEPATH): else: title = struct.identifier - fw("%s\n%s\n\n" % (title, "=" * len(title))) + write_title(fw, title, "=") fw(".. module:: bpy.types\n\n") @@ -615,7 +627,7 @@ def pyrna2sphinx(BASEPATH): sorted_struct_properties.sort(key=lambda prop: prop.identifier) for prop in sorted_struct_properties: - type_descr = prop.get_type_description(class_fmt=":class:`%s`") + type_descr = prop.get_type_description(class_fmt=":class:`%s`", collection_id=_BPY_PROP_COLLECTION_ID) # readonly properties use "data" directive, variables properties use "attribute" directive if 'readonly' in type_descr: fw(" .. data:: %s\n\n" % prop.identifier) @@ -646,7 +658,7 @@ def pyrna2sphinx(BASEPATH): elif func.return_values: # multiple return values fw(" :return (%s):\n" % ", ".join(prop.identifier for prop in func.return_values)) for prop in func.return_values: - type_descr = prop.get_type_description(as_ret=True, class_fmt=":class:`%s`") + type_descr = prop.get_type_description(as_ret=True, class_fmt=":class:`%s`", collection_id=_BPY_PROP_COLLECTION_ID) descr = prop.description if not descr: descr = prop.name @@ -755,38 +767,46 @@ def pyrna2sphinx(BASEPATH): continue write_struct(struct) - # special case, bpy_struct - if _BPY_STRUCT_FAKE: - filepath = os.path.join(BASEPATH, "bpy.types.%s.rst" % _BPY_STRUCT_FAKE) + def fake_bpy_type(class_value, class_name, descr_str, use_subclasses=True): + filepath = os.path.join(BASEPATH, "bpy.types.%s.rst" % class_name) file = open(filepath, "w") fw = file.write - fw("%s\n" % _BPY_STRUCT_FAKE) - fw("=" * len(_BPY_STRUCT_FAKE) + "\n") - fw("\n") + write_title(fw, class_name, "=") + fw(".. module:: bpy.types\n") fw("\n") - subclass_ids = [s.identifier for s in structs.values() if s.base is None if not rna_info.rna_id_ignore(s.identifier)] - if subclass_ids: - fw("subclasses --- \n" + ", ".join((":class:`%s`" % s) for s in sorted(subclass_ids)) + "\n\n") + if use_subclasses: + subclass_ids = [s.identifier for s in structs.values() if s.base is None if not rna_info.rna_id_ignore(s.identifier)] + if subclass_ids: + fw("subclasses --- \n" + ", ".join((":class:`%s`" % s) for s in sorted(subclass_ids)) + "\n\n") - fw(".. class:: %s\n\n" % _BPY_STRUCT_FAKE) - fw(" built-in base class for all classes in bpy.types.\n\n") + fw(".. class:: %s\n\n" % class_name) + fw(" %s\n\n" % descr_str) fw(" .. note::\n\n") - fw(" Note that bpy.types.%s is not actually available from within blender, it only exists for the purpose of documentation.\n\n" % _BPY_STRUCT_FAKE) + fw(" Note that bpy.types.%s is not actually available from within blender, it only exists for the purpose of documentation.\n\n" % class_name) - descr_items = [(key, descr) for key, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()) if not key.startswith("__")] + descr_items = [(key, descr) for key, descr in sorted(class_value.__dict__.items()) if not key.startswith("__")] for key, descr in descr_items: if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet - py_descr2sphinx(" ", fw, descr, "bpy.types", _BPY_STRUCT_FAKE, key) + py_descr2sphinx(" ", fw, descr, "bpy.types", class_name, key) for key, descr in descr_items: if type(descr) == GetSetDescriptorType: - py_descr2sphinx(" ", fw, descr, "bpy.types", _BPY_STRUCT_FAKE, key) + py_descr2sphinx(" ", fw, descr, "bpy.types", class_name, key) file.close() + # write fake classes + if _BPY_STRUCT_FAKE: + class_value = bpy.types.Struct.__bases__[0] + fake_bpy_type(class_value, _BPY_STRUCT_FAKE, "built-in base class for all classes in bpy.types.", use_subclasses=True) + + if _BPY_PROP_COLLECTION_FAKE: + class_value = bpy.data.objects.__class__ + fake_bpy_type(class_value, _BPY_PROP_COLLECTION_FAKE, "built-in class used for all collections.", use_subclasses=False) + # operators def write_ops(): API_BASEURL = "https://svn.blender.org/svnroot/bf-blender/trunk/blender/release/scripts" @@ -802,7 +822,8 @@ def pyrna2sphinx(BASEPATH): fw = file.write title = "%s Operators" % op_module_name.replace("_", " ").title() - fw("%s\n%s\n\n" % (title, "=" * len(title))) + + write_title(fw, title, "=") fw(".. module:: bpy.ops.%s\n\n" % op_module_name) @@ -1074,7 +1095,9 @@ def rna2sphinx(BASEPATH): fw("\n") title = ":mod:`bpy` --- Blender Python Module" - fw("%s\n%s\n\n" % (title, "=" * len(title))) + + write_title(fw, title, "=") + fw(".. module:: bpy.types\n\n") file.close() diff --git a/release/scripts/modules/rna_info.py b/release/scripts/modules/rna_info.py index ac6043da340..74df544b679 100644 --- a/release/scripts/modules/rna_info.py +++ b/release/scripts/modules/rna_info.py @@ -253,7 +253,7 @@ class InfoPropertyRNA: return "%s=%s" % (self.identifier, default) return self.identifier - def get_type_description(self, as_ret=False, as_arg=False, class_fmt="%s"): + def get_type_description(self, as_ret=False, as_arg=False, class_fmt="%s", collection_id="Collection"): type_str = "" if self.fixed_type is None: type_str += self.type @@ -277,9 +277,9 @@ class InfoPropertyRNA: else: if self.type == "collection": if self.collection_type: - collection_str = (class_fmt % self.collection_type.identifier) + " collection of " + collection_str = (class_fmt % self.collection_type.identifier) + (" %s of " % collection_id) else: - collection_str = "Collection of " + collection_str = "%s of " % collection_id else: collection_str = "" diff --git a/source/blender/editors/transform/transform_manipulator.c b/source/blender/editors/transform/transform_manipulator.c index 68ab94b8b4f..fcbe4171a08 100644 --- a/source/blender/editors/transform/transform_manipulator.c +++ b/source/blender/editors/transform/transform_manipulator.c @@ -1566,7 +1566,6 @@ static int manipulator_selectbuf(ScrArea *sa, ARegion *ar, short *mval, float ho return 0; } -int wm_operator_invoke(bContext *C, wmOperatorType *ot, wmEvent *event, PointerRNA *properties, ReportList *reports); /* return 0; nothing happened */ int BIF_do_manipulator(bContext *C, struct wmEvent *event, wmOperator *op) @@ -1623,7 +1622,7 @@ int BIF_do_manipulator(bContext *C, struct wmEvent *event, wmOperator *op) } RNA_boolean_set_array(op->ptr, "constraint_axis", constraint_axis); WM_operator_name_call(C, "TRANSFORM_OT_translate", WM_OP_INVOKE_DEFAULT, op->ptr); - //wm_operator_invoke(C, WM_operatortype_find("TRANSFORM_OT_translate", 0), event, op->ptr, NULL); + //wm_operator_invoke(C, WM_operatortype_find("TRANSFORM_OT_translate", 0), event, op->ptr, NULL, FALSE); } else if (drawflags & MAN_SCALE_C) { switch(drawflags) { @@ -1654,11 +1653,11 @@ int BIF_do_manipulator(bContext *C, struct wmEvent *event, wmOperator *op) } RNA_boolean_set_array(op->ptr, "constraint_axis", constraint_axis); WM_operator_name_call(C, "TRANSFORM_OT_resize", WM_OP_INVOKE_DEFAULT, op->ptr); - //wm_operator_invoke(C, WM_operatortype_find("TRANSFORM_OT_resize", 0), event, op->ptr, NULL); + //wm_operator_invoke(C, WM_operatortype_find("TRANSFORM_OT_resize", 0), event, op->ptr, NULL, FALSE); } else if (drawflags == MAN_ROT_T) { /* trackball need special case, init is different */ - //wm_operator_invoke(C, WM_operatortype_find("TRANSFORM_OT_trackball", 0), event, op->ptr, NULL); WM_operator_name_call(C, "TRANSFORM_OT_trackball", WM_OP_INVOKE_DEFAULT, op->ptr); + //wm_operator_invoke(C, WM_operatortype_find("TRANSFORM_OT_trackball", 0), event, op->ptr, NULL, FALSE); } else if (drawflags & MAN_ROT_C) { switch(drawflags) { @@ -1674,7 +1673,7 @@ int BIF_do_manipulator(bContext *C, struct wmEvent *event, wmOperator *op) } RNA_boolean_set_array(op->ptr, "constraint_axis", constraint_axis); WM_operator_name_call(C, "TRANSFORM_OT_rotate", WM_OP_INVOKE_DEFAULT, op->ptr); - //wm_operator_invoke(C, WM_operatortype_find("TRANSFORM_OT_rotate", 0), event, op->ptr, NULL); + //wm_operator_invoke(C, WM_operatortype_find("TRANSFORM_OT_rotate", 0), event, op->ptr, NULL, FALSE); } } /* after transform, restore drawflags */ diff --git a/source/blender/python/intern/bpy_rna.c b/source/blender/python/intern/bpy_rna.c index 6ae38d66781..0dfc98de487 100644 --- a/source/blender/python/intern/bpy_rna.c +++ b/source/blender/python/intern/bpy_rna.c @@ -3294,6 +3294,14 @@ static PyGetSetDef pyrna_struct_getseters[]= { {NULL, NULL, NULL, NULL, NULL} /* Sentinel */ }; +static char pyrna_prop_collection_keys_doc[] = +".. method:: keys()\n" +"\n" +" Return the identifiers of collection members (matching pythons dict.keys() functionality).\n" +"\n" +" :return: the identifiers for each member of this collection.\n" +" :rtype: list of stings\n" +; static PyObject *pyrna_prop_collection_keys(BPy_PropertyRNA *self) { PyObject *ret= PyList_New(0); @@ -3319,6 +3327,14 @@ static PyObject *pyrna_prop_collection_keys(BPy_PropertyRNA *self) return ret; } +static char pyrna_prop_collection_items_doc[] = +".. method:: items()\n" +"\n" +" Return the identifiers of collection members (matching pythons dict.items() functionality).\n" +"\n" +" :return: (key, value) pairs for each member of this collection.\n" +" :rtype: list of tuples\n" +; static PyObject *pyrna_prop_collection_items(BPy_PropertyRNA *self) { PyObject *ret= PyList_New(0); @@ -3352,6 +3368,14 @@ static PyObject *pyrna_prop_collection_items(BPy_PropertyRNA *self) return ret; } +static char pyrna_prop_collection_values_doc[] = +".. method:: values()\n" +"\n" +" Return the values of collection (matching pythons dict.values() functionality).\n" +"\n" +" :return: the members of this collection.\n" +" :rtype: list\n" +; static PyObject *pyrna_prop_collection_values(BPy_PropertyRNA *self) { /* re-use slice*/ @@ -3414,6 +3438,16 @@ static PyObject *pyrna_struct_as_pointer(BPy_StructRNA *self) return PyLong_FromVoidPtr(self->ptr.data); } +static char pyrna_prop_collection_get_doc[] = +".. method:: get(key, default=None)\n" +"\n" +" Returns the value of the item assigned to key or default when not found (matches pythons dictionary function of the same name).\n" +"\n" +" :arg key: The identifier for the collection member.\n" +" :type key: string\n" +" :arg default: Optional argument for the value to return if *key* is not found.\n" +" :type default: Undefined\n" +; static PyObject *pyrna_prop_collection_get(BPy_PropertyRNA *self, PyObject *args) { PointerRNA newptr; @@ -3804,11 +3838,11 @@ static struct PyMethodDef pyrna_prop_collection_methods[]= { {"foreach_get", (PyCFunction)pyrna_prop_collection_foreach_get, METH_VARARGS, pyrna_prop_collection_foreach_get_doc}, {"foreach_set", (PyCFunction)pyrna_prop_collection_foreach_set, METH_VARARGS, pyrna_prop_collection_foreach_set_doc}, - {"keys", (PyCFunction)pyrna_prop_collection_keys, METH_NOARGS, NULL}, - {"items", (PyCFunction)pyrna_prop_collection_items, METH_NOARGS, NULL}, - {"values", (PyCFunction)pyrna_prop_collection_values, METH_NOARGS, NULL}, + {"keys", (PyCFunction)pyrna_prop_collection_keys, METH_NOARGS, pyrna_prop_collection_keys_doc}, + {"items", (PyCFunction)pyrna_prop_collection_items, METH_NOARGS, pyrna_prop_collection_items_doc}, + {"values", (PyCFunction)pyrna_prop_collection_values, METH_NOARGS, pyrna_prop_collection_values_doc}, - {"get", (PyCFunction)pyrna_prop_collection_get, METH_VARARGS, NULL}, + {"get", (PyCFunction)pyrna_prop_collection_get, METH_VARARGS, pyrna_prop_collection_get_doc}, {NULL, NULL, 0, NULL} }; |