Revision: 25551 http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=25551 Author: campbellbarton Date: 2009-12-25 16:50:53 +0100 (Fri, 25 Dec 2009)
Log Message: ----------- sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators. Modified Paths: -------------- trunk/blender/release/scripts/op/wm.py Added Paths: ----------- trunk/blender/source/blender/python/sphinx_doc_gen.py Removed Paths: ------------- trunk/blender/source/blender/python/epy_doc_gen.py Modified: trunk/blender/release/scripts/op/wm.py =================================================================== --- trunk/blender/release/scripts/op/wm.py 2009-12-25 14:42:00 UTC (rev 25550) +++ trunk/blender/release/scripts/op/wm.py 2009-12-25 15:50:53 UTC (rev 25551) @@ -304,18 +304,18 @@ def execute(self, context): id_split = self.properties.doc_id.split('.') if len(id_split) == 1: # rna, class - url = '%s/bpy.types.%s-class.html' % (self._prefix, id_split[0]) + url = '%s/bpy.types.%s.html' % (self._prefix, id_split[0]) elif len(id_split) == 2: # rna, class.prop class_name, class_prop = id_split if hasattr(bpy.types, class_name.upper() + '_OT_' + class_prop): - url = '%s/bpy.ops.%s-module.html#%s' % \ - (self._prefix, class_name, class_prop) + url = '%s/bpy.ops.%s.html#bpy.ops.%s.%s' % \ + (self._prefix, class_name, class_name, class_prop) else: - # It so happens that epydoc nests these - class_name_full = self._nested_class_string(class_name) - url = '%s/bpy.types.%s-class.html#%s' % \ - (self._prefix, class_name_full, class_prop) + # It so happens that epydoc nests these, not sphinx + # class_name_full = self._nested_class_string(class_name) + url = '%s/bpy.types.%s.html#bpy.types.%s.%s' % \ + (self._prefix, class_name, class_name, class_prop) else: return {'PASS_THROUGH'} Deleted: trunk/blender/source/blender/python/epy_doc_gen.py =================================================================== --- trunk/blender/source/blender/python/epy_doc_gen.py 2009-12-25 14:42:00 UTC (rev 25550) +++ trunk/blender/source/blender/python/epy_doc_gen.py 2009-12-25 15:50:53 UTC (rev 25551) @@ -1,760 +0,0 @@ - # ***** 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 #**** - -script_help_msg = ''' -Usage, -run this script from blenders root path once you have compiled blender - ./blender.bin -P source/blender/python/epy_doc_gen.py - -This will generate python files in "./source/blender/python/doc/bpy" -Generate html docs by running... - - epydoc source/blender/python/doc/bpy/ -v \\ - -o source/blender/python/doc/html \\ - --inheritance=included \\ - --no-sourcecode \\ - --graph=classtree \\ - --graph-font-size=8 - -''' - -# if you dont have graphvis installed ommit the --graph arg. - -# GLOBALS['BASEDIR'] = './source/blender/python/doc' - -import os - -SUBMODULES = {} -INIT_SUBMODULES = {} # store initialized files - -INIT_SUBMODULES_IMPORTS = {} # dont import the same module twice - -def append_package(package_path, mod_name): - - init_path = os.path.join(os.path.dirname(package_path), "__init__.py") - - # avoid double ups - if mod_name: - imports = INIT_SUBMODULES_IMPORTS.setdefault(init_path, []) - if mod_name in imports: - return - imports.append(mod_name) - - try: - os.makedirs(os.path.dirname(init_path)) # make the dirs if they are not there - except: - pass - - # Open the new file for the first time, otherwise keep it open. - f = INIT_SUBMODULES.get(init_path) - if f == None: - f = INIT_SUBMODULES[init_path] = open(init_path, 'w') - - if mod_name: - f.write("import %s\n" % mod_name) - - return f - -def append_package_recursive(package_path, BASEPATH): - ''' - assume the last item of package_path will be a file (not a dir thats created) - ''' - - package_path = os.path.splitext(package_path)[0] # incase of .py - - try: - os.makedirs(os.path.join(BASEPATH, os.path.dirname(package_path))) # make the dirs if they are not there - except: - pass - - new_path = BASEPATH - - for mod_name in package_path.split(os.sep): - init_path = os.path.join(new_path, "__init__.py") - new_path = os.path.join(new_path, mod_name) - append_package(init_path, mod_name) - - -def open_submodule(subpath, BASEPATH): - ''' - This is a utility function that lets us quickly add submodules - ''' - - # create all the package paths leading up to this module - append_package_recursive(subpath, BASEPATH) - - module_name = os.path.basename( os.path.splitext(subpath)[0] ) - mod_path = os.path.join(BASEPATH, subpath) - - # Open the new file for the first time, otherwise keep it open. - f = SUBMODULES.get(mod_path) - if f == None: - f = SUBMODULES[mod_path] = open(mod_path, 'w') - - f = open(mod_path, 'w') - return f - -def close_all(): - for files in (INIT_SUBMODULES.values(), SUBMODULES.values()): - for f in files: - if f.name.endswith('.py'): - f_name = f.name - f.close() - - f = open(f_name, 'a') - f.write("\ndel __package__\n") # annoying, no need do show this - - - f.close() - - -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 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 - - return False - -def write_func(rna, ident, out, func_type): - # Keyword attributes - kw_args = [] # "foo = 1", "bar=0.5", "spam='ENUM'" - kw_arg_attrs = [] # "@type mode: int" - - rna_struct= rna.rna_type - - # Operators and functions work differently - if func_type=='OPERATOR': - rna_func_name = rna_struct.identifier.split("_OT_")[-1] - rna_func_desc = rna_struct.description.strip() - items = rna_struct.properties.items() - else: - rna_func_name = rna.identifier - rna_func_desc = rna.description.strip() - items = rna.parameters.items() - - - for rna_prop_identifier, rna_prop in items: - if rna_id_ignore(rna_prop_identifier): - continue - - # clear vars - val = val_error = val_str = rna_prop_type = None - - # ['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 - - - # only for rna functions, operators should not get pointers as args - if rna_prop_type=='pointer': - rna_prop_type_refine = "L{%s}" % rna_prop.fixed_type.identifier - else: - # Collections/Arrays can have a srna type - rna_prop_srna_type = rna_prop.srna - if rna_prop_srna_type: - print(rna_prop_srna_type.identifier) - rna_prop_type_refine = "L{%s}" % rna_prop_srna_type.identifier - else: - rna_prop_type_refine = rna_prop_type - - del rna_prop_srna_type - - - try: length = rna_prop.array_length - except: length = 0 - - array_str = get_array_str(length) - - if rna_prop.use_return: - kw_type_str= "@rtype: %s%s" % (rna_prop_type_refine, array_str) - kw_param_str= "@return: %s" % (rna_prop.description.strip()) - else: - kw_type_str= "@type %s: %s%s" % (rna_prop_identifier, rna_prop_type_refine, array_str) - kw_param_str= "@param %s: %s" % (rna_prop_identifier, rna_prop.description.strip()) - - kw_param_set = False - - if func_type=='OPERATOR': - try: - val = getattr(rna, rna_prop_identifier) - val_error = False - except: - val = "'<UNDEFINED>'" - val_error = True - - - if val_error: - val_str = val - elif rna_prop_type=='float': - if length==0: - val_str= '%g' % val - if '.' not in val_str and '-' not in val_str: # value could be 1e-05 - 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: @@ Diff output truncated at 10240 characters. @@ _______________________________________________ Bf-blender-cvs mailing list Bf-blender-cvs@blender.org http://lists.blender.org/mailman/listinfo/bf-blender-cvs