[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [31008] branches/soc-2010-nexyon/intern/ audaspace/Python/doc: Audaspace: Updated Python doc generation.
Joerg Mueller
nexyon at gmail.com
Tue Aug 3 14:39:13 CEST 2010
Revision: 31008
http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=31008
Author: nexyon
Date: 2010-08-03 14:39:13 +0200 (Tue, 03 Aug 2010)
Log Message:
-----------
Audaspace: Updated Python doc generation.
Modified Paths:
--------------
branches/soc-2010-nexyon/intern/audaspace/Python/doc/createdocs.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Class.rst
branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Module.rst
branches/soc-2010-nexyon/intern/audaspace/Python/doc/util.py
Added Paths:
-----------
branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Layout.rst
branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/aud.Module.rst
Removed Paths:
-------------
branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Code.rst
Modified: branches/soc-2010-nexyon/intern/audaspace/Python/doc/createdocs.py
===================================================================
--- branches/soc-2010-nexyon/intern/audaspace/Python/doc/createdocs.py 2010-08-03 12:34:42 UTC (rev 31007)
+++ branches/soc-2010-nexyon/intern/audaspace/Python/doc/createdocs.py 2010-08-03 12:39:13 UTC (rev 31008)
@@ -31,13 +31,27 @@
module = doctree.Module('aud', aud)
lookup = TemplateLookup(directories = ['templates'])
-class_tpl = lookup.get_template('Class.rst')
-module_tpl = lookup.get_template('Module.rst')
if 'out' not in os.listdir('.'):
os.mkdir('out')
-open('out/'+module.title+'.rst', 'w').write(module_tpl.render(module=module))
+def findTemplate(lookup, name, end):
+ tpl = None
+ while name:
+ try:
+ tpl = lookup.get_template(name+'.'+end+'.rst')
+ break
+ except:
+ name = name.rpartition('.')[0]
+ if not tpl:
+ tpl = lookup.get_template(end+'.rst')
+ return tpl
+name = module.title
+module_tpl = findTemplate(lookup, name, 'Module')
+open('out/'+name+'.rst', 'w').write(module_tpl.render(module=module))
+
for _class in module.classes:
- open('out/'+module.title+'.'+_class.title+'.rst', 'w').write(class_tpl.render(module=module, _class=_class))
+ name = module.title+'.'+_class.title
+ class_tpl = findTemplate(lookup, name, 'Class')
+ open('out/'+name+'.rst', 'w').write(class_tpl.render(module=module, _class=_class))
Modified: branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Class.rst
===================================================================
--- branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Class.rst 2010-08-03 12:34:42 UTC (rev 31007)
+++ branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Class.rst 2010-08-03 12:39:13 UTC (rev 31008)
@@ -1,32 +1,3 @@
-<%namespace name="util" module="util"/>
-${_class.title}
-${'='*len(_class.title)}
-
-.. module:: ${_class.module.title}
-
-.. class:: ${_class.title}
-
- ${util.indent(_class.doc, 1)}
-
-% if _class.methods:
-% for method in _class.methods:
- .. method:: ${util.indent(method.doc, 2)}
-
-% endfor
-% endif
-% if _class.attributes:
-% for attribute in _class.attributes:
- .. attribute:: ${attribute.title}
-
- ${util.indent(attribute.doc, 2)}
-
-% endfor
-% endif
-% if _class.dates:
-% for data in _class.dates:
- .. data:: ${data.title}
-
- ${util.indent(data.doc, 2)}
-
-% endfor
-% endif
\ No newline at end of file
+<%namespace name="layout" file="Layout.rst"/>
+${layout.class_header(_class)}
+${layout.class_footer(_class)}
Deleted: branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Code.rst
===================================================================
--- branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Code.rst 2010-08-03 12:34:42 UTC (rev 31007)
+++ branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Code.rst 2010-08-03 12:39:13 UTC (rev 31008)
@@ -1,5 +0,0 @@
-<%namespace name="util" module="util"/>
-<%page args="filename"/>
-.. code-block:: python
-
- ${util.indent(open('examples/'+filename).read(), 1)}
\ No newline at end of file
Added: branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Layout.rst
===================================================================
--- branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Layout.rst (rev 0)
+++ branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Layout.rst 2010-08-03 12:39:13 UTC (rev 31008)
@@ -0,0 +1,121 @@
+<%namespace name="util" module="util"/>
+
+<%!
+import os
+%>
+
+<%def name="class_header(_class)">
+${_class.title}
+${'='*len(_class.title)}
+
+.. module:: ${_class.module.title}
+
+.. class:: ${_class.title}
+
+${util.indent(_class.doc, 1)}
+</%def>
+
+<%def name="class_footer(_class)">
+% if _class.methods:
+% for method in _class.methods:
+ .. method:: ${util.indent(method.doc, 2, False)}
+
+${example(_class.module.title+'.'+_class.title+'.'+method.title, 2)}
+% endfor
+% endif
+% if _class.attributes:
+% for attribute in _class.attributes:
+ .. attribute:: ${attribute.title}
+
+${util.indent(attribute.doc, 2)}
+
+% endfor
+% endif
+% if _class.dates:
+% for data in _class.dates:
+ .. data:: ${data.title}
+
+${util.indent(data.doc, 2)}
+
+% endfor
+% endif
+</%def>
+
+<%def name="example(name, indent=0)">
+% if os.path.isfile('examples/'+name+'.py'):
+${util.indent('Usage example:', indent)}
+
+${code(name, indent)}
+%endif
+</%def>
+
+<%def name="code(name, indent=0)">
+${util.indent('.. code-block:: python', indent)}
+
+${util.indent(open('examples/'+name+'.py').read(), indent+1)}
+</%def>
+
+<%def name="module_header(module)">
+${module.title} module
+${'='*(len(module.title)+len(' module'))}
+
+*****
+Intro
+*****
+
+${module.doc}
+
+.. module:: ${module.title}
+
+${example(module.title)}
+</%def>
+
+<%def name="module_classes(module)">
+% if module.classes:
+*******
+Classes
+*******
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ ${module.title}.*
+
+% endif
+</%def>
+
+<%def name="module_functions(module)">
+% if module.functions:
+*********
+Functions
+*********
+
+% for function in module.functions:
+.. function:: ${util.indent(function.doc, 1, False)}
+
+${example(module.title+'.'+function.title, 1)}
+% endfor
+% endif
+</%def>
+
+<%def name="module_dates(module)">
+% if module.dates:
+*********
+Constants
+*********
+
+% for data in module.dates:
+.. data:: ${data.title}
+
+${util.indent(data.doc, 1)}
+
+% endfor
+% endif
+</%def>
+
+<%def name="module_footer(module)">
+${module_classes(module)}
+${module_functions(module)}
+${module_dates(module)}
+</%def>
Modified: branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Module.rst
===================================================================
--- branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Module.rst 2010-08-03 12:34:42 UTC (rev 31007)
+++ branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Module.rst 2010-08-03 12:39:13 UTC (rev 31008)
@@ -1,53 +1,3 @@
-<%namespace name="util" module="util"/>
-${module.title} module
-${'='*(len(module.title)+len(' module'))}
-
-*****
-Intro
-*****
-
-${module.doc}
-
-.. module:: ${module.title}
-
-This interactive session shows a basic usage example of the module:
-<%include file="Code.rst" args="filename='aud.py'"/>
-
-This example shows how the library can even be used to synthesise sounds:
-<%include file="Code.rst" args="filename='tetris.py'"/>
-
-% if module.classes:
-*******
-Classes
-*******
-
-.. toctree::
- :maxdepth: 1
- :glob:
-
- ${module.title}.*
-
-% endif
-% if module.functions:
-*********
-Functions
-*********
-
-% for function in module.functions:
-.. function:: ${util.indent(function.doc, 1)}
-
-% endfor
-% endif
-
-% if module.dates:
-*********
-Constants
-*********
-
-% for data in module.dates:
-.. data:: ${data.title}
-
- ${util.indent(data.doc, 1)}
-
-% endfor
-% endif
\ No newline at end of file
+<%namespace name="layout" file="Layout.rst"/>
+${layout.module_header(module)}
+${layout.module_footer(module)}
Copied: branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/aud.Module.rst (from rev 31005, branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/Module.rst)
===================================================================
--- branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/aud.Module.rst (rev 0)
+++ branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/aud.Module.rst 2010-08-03 12:39:13 UTC (rev 31008)
@@ -0,0 +1,7 @@
+<%namespace name="layout" file="Layout.rst"/>
+${layout.module_header(module)}
+
+This example shows how the library can even be used to synthesise sounds:
+${layout.code('tetris')}
+
+${layout.module_footer(module)}
Modified: branches/soc-2010-nexyon/intern/audaspace/Python/doc/util.py
===================================================================
--- branches/soc-2010-nexyon/intern/audaspace/Python/doc/util.py 2010-08-03 12:34:42 UTC (rev 31007)
+++ branches/soc-2010-nexyon/intern/audaspace/Python/doc/util.py 2010-08-03 12:39:13 UTC (rev 31008)
@@ -17,5 +17,8 @@
#
# ##### END GPL LICENSE BLOCK #####
-def indent(context, str, level):
- return str.replace('\n', '\n' + (' ' * level))
+def indent(context, str, level, first=True):
+ result = str.replace('\n', '\n' + (' ' * level))
+ if first:
+ result = ' ' * level + result
+ return result
More information about the Bf-blender-cvs
mailing list