forked from bartvdbraak/blender
fix [#25688] undocumted functions in pyapi
expose collection function docs.
This commit is contained in:
parent
3384679aec
commit
1b80538fea
@ -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()
|
||||
|
||||
|
@ -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 = ""
|
||||
|
||||
|
@ -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 */
|
||||
|
@ -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}
|
||||
};
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user