diff options
author | Campbell Barton <ideasman42@gmail.com> | 2008-12-19 08:05:23 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2008-12-19 08:05:23 +0300 |
commit | b6121d24238c0e4146161bb0c7f8edc502c424e3 (patch) | |
tree | 8314c2b48edf772c1adac3649c81a65125dd042e /source/blender/python | |
parent | 04428d6750d7309d7c7436c65b465f2b51d3d6a2 (diff) |
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
Diffstat (limited to 'source/blender/python')
-rw-r--r-- | source/blender/python/epy_doc_gen.py | 160 |
1 files changed, 160 insertions, 0 deletions
diff --git a/source/blender/python/epy_doc_gen.py b/source/blender/python/epy_doc_gen.py new file mode 100644 index 00000000000..4ce43f87c5e --- /dev/null +++ b/source/blender/python/epy_doc_gen.py @@ -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@ivar %s: %s\n' % (rna_prop_identifier, rna_desc)) + out.write('\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('\t@ivar %s: %s in (%s)\n' % (rna_prop_identifier, rna_desc, ', '.join(rna_prop.items.keys()))) + out.write('\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('\t@ivar %s: %s\n' % (rna_prop_identifier, rna_desc)) + out.write('\t@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@ivar %s: %s (maximum length of %s)\n' % (rna_prop_identifier, rna_desc, rna_prop.max_length)) + out.write('\t@type %s: %s%s%s\n' % (rna_prop_identifier, rna_prop_type, array_str, readonly_str)) + else: + out.write('\t@ivar %s: %s\n' % (rna_prop_identifier, rna_desc)) + out.write('\t@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') + |