[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [25551] trunk/blender: sphinx rna api documentation generator to replace epydocs
Campbell Barton
ideasman42 at gmail.com
Fri Dec 25 16:50:53 CET 2009
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. @@
More information about the Bf-blender-cvs
mailing list