[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [17939] branches/blender2.5/blender/source /blender/python: epy doc generator that runs inside blender2.5, in background mode.

[Campbell Barton]

Revision: 17939
          http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=17939
Author:   campbellbarton
Date:     2008-12-19 06:05:23 +0100 (Fri, 19 Dec 2008)

Log Message:
-----------
epy doc generator that runs inside blender2.5, in background mode.

Automatic support for...
* cross references to struct types
* extracts descriptions/names
* RNA "base" types are converted to python subclasses
* number min/max, string max length, array's, array lengths, valid enum types, readonly flag.

interesting pages (abusing autobuilder ftp :/)
http://www.graphicall.org/builds/builds/autobuilds/rna/class-tree.html
http://www.graphicall.org/builds/builds/autobuilds/rna/rna.Sequence-class.html
http://www.graphicall.org/builds/builds/autobuilds/rna/identifier-index.html

docs are generated in source/blender/python/doc

Added Paths:
-----------
    branches/blender2.5/blender/source/blender/python/doc/
    branches/blender2.5/blender/source/blender/python/epy_doc_gen.py

Added: branches/blender2.5/blender/source/blender/python/epy_doc_gen.py
===================================================================
--- branches/blender2.5/blender/source/blender/python/epy_doc_gen.py	                        (rev 0)
+++ branches/blender2.5/blender/source/blender/python/epy_doc_gen.py	2008-12-19 05:05:23 UTC (rev 17939)
@@ -0,0 +1,160 @@
+ # ***** 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 rna2epy(target_path):
+	
+	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 write_struct(rna_struct):
+		identifier = rna_struct.identifier
+		
+		rna_base = rna_struct.base
+		
+		if rna_base:
+			out.write('class %s(%s):\n' % (identifier, rna_base.identifier))
+		else:
+			out.write('class %s:\n' % identifier)
+		
+		out.write('\t"""\n')
+		
+		title = 'The %s Object' % rna_struct.name
+		
+		out.write('\t%s\n' %  title)
+		out.write('\t%s\n' %  ('=' * len(title)))
+		out.write('\t\t%s\n' %  rna_struct.description)
+		
+		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
+			
+			if length > 0:	array_str = ' array of %d items' % length
+			else:		array_str = ''
+			
+			if rna_prop.readonly:	readonly_str = ' (readonly)'
+			else:				readonly_str = ''
+			
+			if rna_prop_ptr: # Use the pointer type
+				out.write('\t at ivar %s: %s\n' %  (rna_prop_identifier, rna_desc))
+				out.write('\t at 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('\t at ivar %s: %s in (%s)\n' %  (rna_prop_identifier, rna_desc, ', '.join(rna_prop.items.keys())))
+					out.write('\t at 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('\t at ivar %s: %s\n' %  (rna_prop_identifier, rna_desc))
+					out.write('\t at type %s: %s%s%s in [%s, %s]\n' %  (rna_prop_identifier, rna_prop_type, array_str, range_str(rna_prop.hard_min), range_str(rna_prop.hard_max), readonly_str ))
+				elif rna_prop_type == 'string':
+					out.write('\t at ivar %s: %s (maximum length of %s)\n' %  (rna_prop_identifier, rna_desc, rna_prop.max_length))
+					out.write('\t at type %s: %s%s%s\n' %  (rna_prop_identifier, rna_prop_type, array_str, readonly_str))
+				else:
+					out.write('\t at ivar %s: %s\n' %  (rna_prop_identifier, rna_desc))
+					out.write('\t at type %s: %s%s%s\n' %  (rna_prop_identifier, rna_prop_type, array_str, readonly_str))
+				
+			
+		out.write('\t"""\n\n')
+	
+	
+	out = open(target_path, 'w')
+
+	def base_id(rna_struct):
+		try:		return rna_struct.base.identifier
+		except:	return None
+
+	structs = [(base_id(rna_struct), rna_struct.identifier, rna_struct) for rna_struct in bpydoc.structs.values()]
+	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
+	
+	structs = [data[2] for data in structs]
+	# Done ordering structs
+	
+	
+	for rna_struct in structs:
+		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')
+
+if __name__ == '__main__':
+	rna2epy('source/blender/python/doc/rna.py')
+