# ***** BEGIN GPL LICENSE BLOCK ***** # # This program is free software; you can redistribute it and/or # modify it under the terms of the GNU General Public License # as published by the Free Software Foundation; either version 2 # of the License, or (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software Foundation, # Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. # # Contributor(s): Campbell Barton # # #**** END GPL LICENSE BLOCK #**** # Usage, # run this script from blenders root path once you have compiled blender # ./blender.bin -b -P source/blender/python/epy_doc_gen.py # # This will generate rna.py, generate html docs by running... # epydoc source/blender/python/doc/rna.py -o source/blender/python/doc/html -v --no-sourcecode --name="RNA API" --url="http://brechtvanlommelfanclub.com" --graph=classtree # # if you dont have graphvis installed ommit the --graph arg. def range_str(val): if val < -10000000: return '-inf' if val > 10000000: return 'inf' if type(val)==float: return '%g' % val else: return str(val) def get_array_str(length): if length > 0: return ' array of %d items' % length else: return '' def full_rna_struct_path(rna_struct): ''' Needed when referencing one struct from another ''' nested = rna_struct.nested if nested: return "%s.%s" % (full_rna_struct_path(nested), rna_struct.identifier) else: return rna_struct.identifier def rna2epy(target_path): # Use for faster lookups # use rna_struct.identifier as the key for each dict rna_full_path_dict = {} # store the result of full_rna_struct_path(rna_struct) rna_children_dict = {} # store all rna_structs nested from here rna_references_dict = {} # store a list of rna path strings that reference this type def write_struct(rna_struct, ident): identifier = rna_struct.identifier rna_base = rna_struct.base if rna_base: out.write(ident+ 'class %s(%s):\n' % (identifier, rna_base.identifier)) else: out.write(ident+ 'class %s:\n' % identifier) out.write(ident+ '\t"""\n') title = 'The %s Object' % rna_struct.name out.write(ident+ '\t%s\n' % title) out.write(ident+ '\t%s\n' % ('=' * len(title))) out.write(ident+ '\t\t%s\n' % rna_struct.description) # For convenience, give a list of all places were used. rna_refs= rna_references_dict[identifier] if rna_refs: out.write(ident+ '\t\t\n') out.write(ident+ '\t\tReferences\n') out.write(ident+ '\t\t==========\n') for rna_ref_string in rna_refs: out.write(ident+ '\t\t\t- L{%s}\n' % rna_ref_string) out.write(ident+ '\t\t\n') else: out.write(ident+ '\t\t\n') out.write(ident+ '\t\t(no references to this struct found)\n') out.write(ident+ '\t\t\n') for rna_prop_identifier, rna_prop in rna_struct.properties.items(): if rna_prop_identifier=='RNA': continue if rna_prop_identifier=='rna_type': continue rna_desc = rna_prop.description if not rna_desc: rna_desc = rna_prop.name if not rna_desc: rna_desc = 'Note - No documentation for this property!' rna_prop_type = rna_prop.type.lower() if rna_prop_type=='collection': collection_str = 'Collection of ' else: collection_str = '' try: rna_prop_ptr = rna_prop.fixed_type except: rna_prop_ptr = None try: length = rna_prop.array_length except: length = 0 array_str = get_array_str(length) if rna_prop.editable: readonly_str = '' else: readonly_str = ' (readonly)' if rna_prop_ptr: # Use the pointer type out.write(ident+ '\t@ivar %s: %s\n' % (rna_prop_identifier, rna_desc)) out.write(ident+ '\t@type %s: %sL{%s}%s%s\n' % (rna_prop_identifier, collection_str, rna_prop_ptr.identifier, array_str, readonly_str)) else: if rna_prop_type == 'enum': out.write(ident+ '\t@ivar %s: %s in (%s)\n' % (rna_prop_identifier, rna_desc, ', '.join(rna_prop.items.keys()))) out.write(ident+ '\t@type %s: %s%s%s\n' % (rna_prop_identifier, rna_prop_type, array_str, readonly_str)) elif rna_prop_type == 'int' or rna_prop_type == 'float': out.write(ident+ '\t@ivar %s: %s\n' % (rna_prop_identifier, rna_desc)) out.write(ident+ '\t@type %s: %s%s%s in [%s, %s]\n' % (rna_prop_identifier, rna_prop_type, array_str, readonly_str, range_str(rna_prop.hard_min), range_str(rna_prop.hard_max) )) elif rna_prop_type == 'string': out.write(ident+ '\t@ivar %s: %s (maximum length of %s)\n' % (rna_prop_identifier, rna_desc, rna_prop.max_length)) out.write(ident+ '\t@type %s: %s%s%s\n' % (rna_prop_identifier, rna_prop_type, array_str, readonly_str)) else: out.write(ident+ '\t@ivar %s: %s\n' % (rna_prop_identifier, rna_desc)) out.write(ident+ '\t@type %s: %s%s%s\n' % (rna_prop_identifier, rna_prop_type, array_str, readonly_str)) out.write(ident+ '\t"""\n\n') # Now write children recursively for child in rna_children_dict[identifier]: write_struct(child, ident + '\t') out = open(target_path, 'w') def base_id(rna_struct): try: return rna_struct.base.identifier except: return '' # invalid id #structs = [(base_id(rna_struct), rna_struct.identifier, rna_struct) for rna_struct in bpy.doc.structs.values()] ''' structs = [] for rna_struct in bpy.doc.structs.values(): structs.append( (base_id(rna_struct), rna_struct.identifier, rna_struct) ) ''' structs = [] for rna_type_name in dir(bpy.types): rna_type = getattr(bpy.types, rna_type_name) if hasattr(rna_type, '__rna__'): #if not rna_type_name.startswith('__'): rna_struct = rna_type.__rna__ identifier = rna_struct.identifier structs.append( (base_id(rna_struct), identifier, rna_struct) ) # Store full rna path 'GameObjectSettings' -> 'Object.GameObjectSettings' rna_full_path_dict[identifier] = full_rna_struct_path(rna_struct) # fill in these later rna_children_dict[identifier]= [] rna_references_dict[identifier]= [] else: print("Ignoring", rna_type_name) structs.sort() # not needed but speeds up sort below, setting items without an inheritance first # Arrange so classes are always defined in the correct order deps_ok = False while deps_ok == False: deps_ok = True rna_done = set() for i, (rna_base, identifier, rna_struct) in enumerate(structs): rna_done.add(identifier) if rna_base and rna_base not in rna_done: deps_ok = False data = structs.pop(i) ok = False while i < len(structs): if structs[i][1]==rna_base: structs.insert(i+1, data) # insert after the item we depend on. ok = True break i+=1 if not ok: print('Dependancy "%s" could not be found for "%s"' % (identifier, rna_base)) break # Done ordering structs # precalc vars to avoid a lot of looping for (rna_base, identifier, rna_struct) in structs: # rna_struct_path = full_rna_struct_path(rna_struct) rna_struct_path = rna_full_path_dict[identifier] for rna_prop_identifier, rna_prop in rna_struct.properties.items(): if rna_prop_identifier=='RNA': continue if rna_prop_identifier=='rna_type': continue try: rna_prop_ptr = rna_prop.fixed_type except: rna_prop_ptr = None # Does this property point to me? if rna_prop_ptr: rna_references_dict[rna_prop_ptr.identifier].append( "%s.%s" % (rna_struct_path, rna_prop_identifier) ) # Store nested children nested = rna_struct.nested if nested: rna_children_dict[nested.identifier].append(rna_struct) # Sort the refs, just reads nicer for rna_refs in rna_references_dict.values(): rna_refs.sort() for (rna_base, identifier, rna_struct) in structs: if rna_struct.nested: continue write_struct(rna_struct, '') out.write('\n') out.close() # # We could also just run.... # os.system('epydoc source/blender/python/doc/rna.py -o ./source/blender/python/doc/html -v') # Write graphviz out= open(target_path.replace('.py', '.dot'), 'w') out.write('digraph "rna data api" {\n') out.write('\tnode [style=filled, shape = "box"];\n') out.write('\toverlap=false;\n') out.write('\trankdir = LR;\n') out.write('\tsplines=true;\n') out.write('\tratio=auto;\n') out.write('\tsize="10,10"\n') #out.write('\tpage="8.5,11"\n') #out.write('\tcenter=""\n') def isop(rna_struct): return '_OT_' in rna_struct.identifier for (rna_base, identifier, rna_struct) in structs: if isop(rna_struct): continue base = rna_struct.base out.write('\t"%s";\n' % identifier) for (rna_base, identifier, rna_struct) in structs: if isop(rna_struct): continue base = rna_struct.base if base and not isop(base): out.write('\t"%s" -> "%s" [label="(base)" weight=1.0];\n' % (base.identifier, identifier)) nested = rna_struct.nested if nested and not isop(nested): out.write('\t"%s" -> "%s" [label="(nested)" weight=1.0];\n' % (nested.identifier, identifier)) rna_refs= rna_references_dict[identifier] for rna_ref_string in rna_refs: if '_OT_' in rna_ref_string: continue ref = rna_ref_string.split('.')[-2] out.write('\t"%s" -> "%s" [label="%s" weight=0.01];\n' % (ref, identifier, rna_ref_string)) out.write('}\n') out.close() # # We could also just run.... # os.system('dot source/blender/python/doc/rna.dot -Tsvg -o ./source/blender/python/doc/rna.svg') def op2epy(target_path): out = open(target_path, 'w') operators = dir(bpy.ops) operators.remove('add') operators.remove('remove') operators.sort() for op in operators: if op.startswith('__'): continue # Keyword attributes kw_args = [] # "foo = 1", "bar=0.5", "spam='ENUM'" kw_arg_attrs = [] # "@type mode: int" # rna = getattr(bpy.types, op).__rna__ rna = bpy.ops.__rna__(op) rna_struct = rna.rna_type # print (dir(rna)) # print (dir(rna_struct)) for rna_prop_identifier, rna_prop in rna_struct.properties.items(): if rna_prop_identifier=='rna_type': continue # ['rna_type', 'name', 'array_length', 'description', 'hard_max', 'hard_min', 'identifier', 'precision', 'readonly', 'soft_max', 'soft_min', 'step', 'subtype', 'type'] #rna_prop= op_rna.rna_type.properties[attr] rna_prop_type = rna_prop.type.lower() # enum, float, int, boolean try: length = rna_prop.array_length except: length = 0 array_str = get_array_str(length) try: val = getattr(rna, rna_prop_identifier) val_error = False except: val = "''" val_error = True kw_type_str= "@type %s: %s%s" % (rna_prop_identifier, rna_prop_type, array_str) kw_param_str= "@param %s: %s" % (rna_prop_identifier, rna_prop.description) kw_param_set = False if val_error: val_str = val elif rna_prop_type=='float': if length==0: val_str= '%g' % val if '.' not in val_str: val_str += '.0' else: # array val_str = str(tuple(val)) kw_param_str += (' in (%s, %s)' % (range_str(rna_prop.hard_min), range_str(rna_prop.hard_max))) kw_param_set= True elif rna_prop_type=='int': if length==0: val_str='%d' % val else: val_str = str(tuple(val)) # print(dir(rna_prop)) kw_param_str += (' in (%s, %s)' % (range_str(rna_prop.hard_min), range_str(rna_prop.hard_max))) # These strings dont have a max length??? #kw_param_str += ' (maximum length of %s)' % (rna_prop.max_length) kw_param_set= True elif rna_prop_type=='boolean': if length==0: if val: val_str='True' else: val_str='False' else: val_str = str(tuple(val)) elif rna_prop_type=='enum': # no array here? val_str="'%s'" % val kw_param_str += (' in (%s)' % ', '.join(rna_prop.items.keys())) kw_param_set= True elif rna_prop_type=='string': # no array here? val_str='"%s"' % val # todo - collection - array # print (rna_prop.type) kw_args.append('%s = %s' % (rna_prop_identifier, val_str)) # stora kw_arg_attrs.append(kw_type_str) if kw_param_set: kw_arg_attrs.append(kw_param_str) out.write('def %s(%s):\n' % (op, ', '.join(kw_args))) out.write('\t"""\n') out.write('\t%s\n' % rna_struct.description) for desc in kw_arg_attrs: out.write('\t%s\n' % desc) out.write('\t@rtype: None\n') out.write('\t"""\n') out.write('\n') out.close() if __name__ == '__main__': rna2epy('source/blender/python/doc/rna.py') op2epy('source/blender/python/doc/bpyoperator.py')