[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [28115] trunk/blender: rna/py/ reference doc improvements..
Campbell Barton
ideasman42 at gmail.com
Sat Apr 10 20:36:27 CEST 2010
Revision: 28115
http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=28115
Author: campbellbarton
Date: 2010-04-10 20:35:50 +0200 (Sat, 10 Apr 2010)
Log Message:
-----------
rna/py/reference doc improvements..
- vectors now respect min/max settings.
- keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails.
reference docs...
- added docstrings for remaining python bpy_struct functions
- added fake class for docs, bpy_struct, which is the base class of everything in bpy.types
- improved inherictance references for struct classes, include bpy_struct members.
Modified Paths:
--------------
trunk/blender/release/scripts/modules/rna_info.py
trunk/blender/source/blender/python/doc/sphinx_doc_gen.py
trunk/blender/source/blender/python/intern/bpy_rna.c
Modified: trunk/blender/release/scripts/modules/rna_info.py
===================================================================
--- trunk/blender/release/scripts/modules/rna_info.py 2010-04-10 14:46:02 UTC (rev 28114)
+++ trunk/blender/release/scripts/modules/rna_info.py 2010-04-10 18:35:50 UTC (rev 28115)
@@ -25,6 +25,7 @@
# use to strip python paths
script_paths = bpy.utils.script_paths()
+_FAKE_STRUCT_SUBCLASS = True
def _get_direct_attr(rna_type, attr):
props = getattr(rna_type, attr)
@@ -44,7 +45,20 @@
def get_direct_functions(rna_type):
return _get_direct_attr(rna_type, "functions")
+def rna_id_ignore(rna_id):
+ if rna_id == "rna_type":
+ return True
+ if "_OT_" in rna_id:
+ return True
+ if "_MT_" in rna_id:
+ return True
+ if "_PT_" in rna_id:
+ return True
+ if "_HT_" in rna_id:
+ return True
+ return False
+
def range_str(val):
if val < -10000000:
return '-inf'
@@ -135,17 +149,17 @@
def __repr__(self):
- txt = ''
+ txt = ""
txt += self.identifier
if self.base:
- txt += '(%s)' % self.base.identifier
- txt += ': ' + self.description + '\n'
+ txt += "(%s)" % self.base.identifier
+ txt += ": " + self.description + "\n"
for prop in self.properties:
- txt += prop.__repr__() + '\n'
+ txt += prop.__repr__() + "\n"
for func in self.functions:
- txt += func.__repr__() + '\n'
+ txt += func.__repr__() + "\n"
return txt
@@ -377,7 +391,6 @@
def GetInfoOperatorRNA(bl_rna):
return _GetInfoRNA(bl_rna, InfoOperatorRNA)
-
def BuildRNAInfo():
# Use for faster lookups
# use rna_struct.identifier as the key for each dict
@@ -387,20 +400,7 @@
rna_references_dict = {} # store a list of rna path strings that reference this type
# rna_functions_dict = {} # store all functions directly in this type (not inherited)
- def rna_id_ignore(rna_id):
- if rna_id == "rna_type":
- return True
- if "_OT_" in rna_id:
- return True
- if "_MT_" in rna_id:
- return True
- if "_PT_" in rna_id:
- return True
- if "_HT_" in rna_id:
- return True
- return False
-
def full_rna_struct_path(rna_struct):
'''
Needed when referencing one struct from another
Modified: trunk/blender/source/blender/python/doc/sphinx_doc_gen.py
===================================================================
--- trunk/blender/source/blender/python/doc/sphinx_doc_gen.py 2010-04-10 14:46:02 UTC (rev 28114)
+++ trunk/blender/source/blender/python/doc/sphinx_doc_gen.py 2010-04-10 18:35:50 UTC (rev 28115)
@@ -50,6 +50,8 @@
EXAMPLE_SET = set()
EXAMPLE_SET_USED = set()
+_BPY_STRUCT_FAKE = "bpy_struct"
+
def range_str(val):
if val < -10000000: return '-inf'
if val > 10000000: return 'inf'
@@ -122,6 +124,23 @@
write_indented_lines(ident + " ", fw, py_func.__doc__.strip())
fw("\n")
+
+def py_descr2sphinx(ident, fw, descr, module_name, type_name, identifier):
+ doc = descr.__doc__
+ if not doc:
+ doc = "Undocumented"
+
+ if type(descr) == GetSetDescriptorType:
+ fw(ident + ".. attribute:: %s\n\n" % identifier)
+ write_indented_lines(ident, fw, doc, False)
+ elif type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
+ write_indented_lines(ident, fw, doc, False)
+ else:
+ raise TypeError("type was not GetSetDescriptorType or MethodDescriptorType")
+
+ write_example_ref(ident, fw, module_name + "." + type_name + "." + identifier)
+ fw("\n")
+
def py_c_func2sphinx(ident, fw, identifier, py_func, is_class=True):
'''
c defined function to sphinx.
@@ -169,10 +188,10 @@
# write members of the module
# only tested with PyStructs which are not exactly modules
- for attribute, descr in sorted(type(module).__dict__.items()):
+ for key, descr in sorted(type(module).__dict__.items()):
if type(descr) == types.MemberDescriptorType:
if descr.__doc__:
- fw(".. data:: %s\n\n" % attribute)
+ fw(".. data:: %s\n\n" % key)
write_indented_lines(" ", fw, descr.__doc__, False)
fw("\n")
@@ -202,37 +221,26 @@
else:
print("\tnot documenting %s.%s" % (module_name, attribute))
# TODO, more types...
-
+
# write collected classes now
- for (attribute, value) in classes:
+ for (type_name, value) in classes:
# May need to be its own function
- fw(".. class:: %s\n\n" % attribute)
+ fw(".. class:: %s\n\n" % type_name)
if value.__doc__:
write_indented_lines(" ", fw, value.__doc__, False)
fw("\n")
- write_example_ref(" ", fw, module_name + "." + attribute)
+ write_example_ref(" ", fw, module_name + "." + type_name)
- for key in sorted(value.__dict__.keys()):
- if key.startswith("__"):
- continue
- descr = value.__dict__[key]
+ descr_items = [(key, descr) for key, descr in sorted(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, module_name, type_name, key)
+
+ for key, descr in descr_items:
if type(descr) == GetSetDescriptorType:
- if descr.__doc__:
- fw(" .. attribute:: %s\n\n" % key)
- write_indented_lines(" ", fw, descr.__doc__, False)
- write_example_ref(" ", fw, module_name + "." + attribute + "." + key)
- fw("\n")
+ py_descr2sphinx(" ", fw, descr, module_name, type_name, key)
- for key in sorted(value.__dict__.keys()):
- if key.startswith("__"):
- continue
- descr = value.__dict__[key]
- if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
- if descr.__doc__:
- write_indented_lines(" ", fw, descr.__doc__, False)
- write_example_ref(" ", fw, module_name + "." + attribute + "." + key)
- fw("\n")
-
fw("\n\n")
file.close()
@@ -400,8 +408,14 @@
file = open(filepath, "w")
fw = file.write
- if struct.base:
- title = "%s(%s)" % (struct.identifier, struct.base.identifier)
+ base_id = getattr(struct.base, "identifier", "")
+
+ if _BPY_STRUCT_FAKE:
+ if not base_id:
+ base_id = _BPY_STRUCT_FAKE
+
+ if base_id:
+ title = "%s(%s)" % (struct.identifier, base_id)
else:
title = struct.identifier
@@ -409,26 +423,34 @@
fw(".. module:: bpy.types\n\n")
- bases = struct.get_bases()
- if bases:
- if len(bases) > 1:
+ base_ids = [base.identifier for base in struct.get_bases()]
+
+ if _BPY_STRUCT_FAKE:
+ base_ids.append(_BPY_STRUCT_FAKE)
+
+ base_ids.reverse()
+
+ if base_ids:
+ if len(base_ids) > 1:
fw("base classes --- ")
else:
fw("base class --- ")
- fw(", ".join([(":class:`%s`" % base.identifier) for base in reversed(bases)]))
+ fw(", ".join([(":class:`%s`" % base_id) for base_id in base_ids]))
fw("\n\n")
- subclasses = [s for s in structs.values() if s.base is struct]
+ subclass_ids = [s.identifier for s in structs.values() if s.base is struct if not rna_info.rna_id_ignore(s.identifier)]
+ if subclass_ids:
+ fw("subclasses --- \n" + ", ".join([(":class:`%s`" % s) for s in subclass_ids]) + "\n\n")
- if subclasses:
- fw("subclasses --- \n")
- fw(", ".join([(":class:`%s`" % s.identifier) for s in subclasses]))
- fw("\n\n")
+ base_id = getattr(struct.base, "identifier", "")
+
+ if _BPY_STRUCT_FAKE:
+ if not base_id:
+ base_id = _BPY_STRUCT_FAKE
-
- if struct.base:
- fw(".. class:: %s(%s)\n\n" % (struct.identifier, struct.base.identifier))
+ if base_id:
+ fw(".. class:: %s(%s)\n\n" % (struct.identifier, base_id))
else:
fw(".. class:: %s\n\n" % struct.identifier)
@@ -479,28 +501,31 @@
pyfunc2sphinx(" ", fw, identifier, py_func, is_class=True)
del py_funcs, py_func
- # c/python methods, only for the base class
- if struct.identifier == "Struct":
- for attribute, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()):
- if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
- if descr.__doc__:
- write_indented_lines(" ", fw, descr.__doc__, False)
- write_example_ref(" ", fw, struct.identifier + "." + attribute)
- fw("\n")
-
lines = []
- if struct.base:
+ if struct.base or _BPY_STRUCT_FAKE:
bases = list(reversed(struct.get_bases()))
-
+
# props
lines[:] = []
+
+ if _BPY_STRUCT_FAKE:
+ descr_items = [(key, descr) for key, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()) if not key.startswith("__")]
+
+ if _BPY_STRUCT_FAKE:
+ for key, descr in descr_items:
+ if type(descr) == GetSetDescriptorType:
+ lines.append("* :class:`%s.%s`\n" % (_BPY_STRUCT_FAKE, key))
+
for base in bases:
for prop in base.properties:
lines.append("* :class:`%s.%s`\n" % (base.identifier, prop.identifier))
for identifier, py_prop in base.get_py_properties():
lines.append("* :class:`%s.%s`\n" % (base.identifier, identifier))
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list