[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [27187] trunk/blender/source/blender/ python: examples for autogenerated docs are now implicit and used when available.
Campbell Barton
ideasman42 at gmail.com
Sun Feb 28 14:45:08 CET 2010
Revision: 27187
http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=27187
Author: campbellbarton
Date: 2010-02-28 14:45:08 +0100 (Sun, 28 Feb 2010)
Log Message:
-----------
examples for autogenerated docs are now implicit and used when available.
This means adding the file "bpy.props.py" in the examples dir will automatically be used when generating docs, unused examples give warnings.
Modified Paths:
--------------
trunk/blender/source/blender/python/doc/sphinx_doc_gen.py
trunk/blender/source/blender/python/generic/Mathutils.c
trunk/blender/source/blender/python/generic/euler.c
trunk/blender/source/blender/python/generic/matrix.c
trunk/blender/source/blender/python/generic/quat.c
trunk/blender/source/blender/python/generic/vector.c
Added Paths:
-----------
trunk/blender/source/blender/python/doc/examples/Mathutils.Euler.py
trunk/blender/source/blender/python/doc/examples/Mathutils.Matrix.py
trunk/blender/source/blender/python/doc/examples/Mathutils.Quaternion.py
trunk/blender/source/blender/python/doc/examples/Mathutils.Vector.py
trunk/blender/source/blender/python/doc/examples/Mathutils.py
Removed Paths:
-------------
trunk/blender/source/blender/python/doc/examples/mathutils.py
trunk/blender/source/blender/python/doc/examples/mathutils_euler.py
trunk/blender/source/blender/python/doc/examples/mathutils_matrix.py
trunk/blender/source/blender/python/doc/examples/mathutils_quat.py
trunk/blender/source/blender/python/doc/examples/mathutils_vector.py
Copied: trunk/blender/source/blender/python/doc/examples/Mathutils.Euler.py (from rev 27179, trunk/blender/source/blender/python/doc/examples/mathutils_euler.py)
===================================================================
--- trunk/blender/source/blender/python/doc/examples/Mathutils.Euler.py (rev 0)
+++ trunk/blender/source/blender/python/doc/examples/Mathutils.Euler.py 2010-02-28 13:45:08 UTC (rev 27187)
@@ -0,0 +1,3 @@
+import Mathutils
+
+# todo
\ No newline at end of file
Copied: trunk/blender/source/blender/python/doc/examples/Mathutils.Matrix.py (from rev 27179, trunk/blender/source/blender/python/doc/examples/mathutils_matrix.py)
===================================================================
--- trunk/blender/source/blender/python/doc/examples/Mathutils.Matrix.py (rev 0)
+++ trunk/blender/source/blender/python/doc/examples/Mathutils.Matrix.py 2010-02-28 13:45:08 UTC (rev 27187)
@@ -0,0 +1,3 @@
+import Mathutils
+
+# todo
\ No newline at end of file
Copied: trunk/blender/source/blender/python/doc/examples/Mathutils.Quaternion.py (from rev 27179, trunk/blender/source/blender/python/doc/examples/mathutils_quat.py)
===================================================================
--- trunk/blender/source/blender/python/doc/examples/Mathutils.Quaternion.py (rev 0)
+++ trunk/blender/source/blender/python/doc/examples/Mathutils.Quaternion.py 2010-02-28 13:45:08 UTC (rev 27187)
@@ -0,0 +1,3 @@
+import Mathutils
+
+# todo
\ No newline at end of file
Copied: trunk/blender/source/blender/python/doc/examples/Mathutils.Vector.py (from rev 27179, trunk/blender/source/blender/python/doc/examples/mathutils_vector.py)
===================================================================
--- trunk/blender/source/blender/python/doc/examples/Mathutils.Vector.py (rev 0)
+++ trunk/blender/source/blender/python/doc/examples/Mathutils.Vector.py 2010-02-28 13:45:08 UTC (rev 27187)
@@ -0,0 +1,55 @@
+import Mathutils
+
+# zero length vector
+vec = Mathutils.Vector(0, 0, 1)
+
+# unit length vector
+vec_a = vec.copy().normalize()
+
+vec_b = Mathutils.Vector(0, 1, 2)
+
+vec2d = Mathutils.Vector(1, 2)
+vec3d = Mathutils.Vector([1, 0, 0])
+vec4d = vec_a.copy().resize4D()
+
+# other mathutuls types
+quat = Mathutils.Quaternion()
+matrix = Mathutils.Matrix()
+
+# Comparison operators can be done on Vector classes:
+
+# greater and less then test vector length.
+vec_a > vec_b
+vec_a >= vec_b
+vec_a < vec_b
+vec_a <= vec_b
+
+# ==, != test vector values e.g. 1,2,3 != 3,2,1 even if they are the same length
+vec_a == vec_b
+vec_a != vec_b
+
+
+# Math can be performed on Vector classes
+vec_a + vec_b
+vec_a - vec_b
+vec_a * vec_b
+vec_a * 10.0
+vec_a * matrix
+vec_a * vec_b
+vec_a * quat
+-vec_a
+
+
+# You can access a vector object like a sequence
+x = vec_a[0]
+len(vec)
+vec_a[:] = vec_b
+vec2d[:] = vec3d[:2]
+
+
+# Vectors support 'swizzle' operations
+# See http://en.wikipedia.org/wiki/Swizzling_(computer_graphics)
+vec.xyz = vec.zyx
+vec.xy = vec4d.zw
+vec.xyz = vec4d.wzz
+vec4d.wxyz = vec.yxyx
Copied: trunk/blender/source/blender/python/doc/examples/Mathutils.py (from rev 27179, trunk/blender/source/blender/python/doc/examples/mathutils.py)
===================================================================
--- trunk/blender/source/blender/python/doc/examples/Mathutils.py (rev 0)
+++ trunk/blender/source/blender/python/doc/examples/Mathutils.py 2010-02-28 13:45:08 UTC (rev 27187)
@@ -0,0 +1,17 @@
+import Mathutils
+
+vec = Mathutils.Vector(1.0, 2.0, 3.0)
+
+mat_rot = Mathutils.RotationMatrix(90, 4, 'X')
+mat_trans = Mathutils.TranslationMatrix(vec)
+
+mat = mat_trans * mat_rot
+mat.invert()
+
+mat3 = mat.rotation_part()
+quat1 = mat.to_quat()
+quat2 = mat3.to_quat()
+
+angle = quat1.difference(quat2)
+
+print(angle)
\ No newline at end of file
Deleted: trunk/blender/source/blender/python/doc/examples/mathutils.py
===================================================================
--- trunk/blender/source/blender/python/doc/examples/mathutils.py 2010-02-28 11:54:48 UTC (rev 27186)
+++ trunk/blender/source/blender/python/doc/examples/mathutils.py 2010-02-28 13:45:08 UTC (rev 27187)
@@ -1,17 +0,0 @@
-import Mathutils
-
-vec = Mathutils.Vector(1.0, 2.0, 3.0)
-
-mat_rot = Mathutils.RotationMatrix(90, 4, 'X')
-mat_trans = Mathutils.TranslationMatrix(vec)
-
-mat = mat_trans * mat_rot
-mat.invert()
-
-mat3 = mat.rotation_part()
-quat1 = mat.to_quat()
-quat2 = mat3.to_quat()
-
-angle = quat1.difference(quat2)
-
-print(angle)
\ No newline at end of file
Deleted: trunk/blender/source/blender/python/doc/examples/mathutils_euler.py
===================================================================
--- trunk/blender/source/blender/python/doc/examples/mathutils_euler.py 2010-02-28 11:54:48 UTC (rev 27186)
+++ trunk/blender/source/blender/python/doc/examples/mathutils_euler.py 2010-02-28 13:45:08 UTC (rev 27187)
@@ -1,3 +0,0 @@
-import Mathutils
-
-# todo
\ No newline at end of file
Deleted: trunk/blender/source/blender/python/doc/examples/mathutils_matrix.py
===================================================================
--- trunk/blender/source/blender/python/doc/examples/mathutils_matrix.py 2010-02-28 11:54:48 UTC (rev 27186)
+++ trunk/blender/source/blender/python/doc/examples/mathutils_matrix.py 2010-02-28 13:45:08 UTC (rev 27187)
@@ -1,3 +0,0 @@
-import Mathutils
-
-# todo
\ No newline at end of file
Deleted: trunk/blender/source/blender/python/doc/examples/mathutils_quat.py
===================================================================
--- trunk/blender/source/blender/python/doc/examples/mathutils_quat.py 2010-02-28 11:54:48 UTC (rev 27186)
+++ trunk/blender/source/blender/python/doc/examples/mathutils_quat.py 2010-02-28 13:45:08 UTC (rev 27187)
@@ -1,3 +0,0 @@
-import Mathutils
-
-# todo
\ No newline at end of file
Deleted: trunk/blender/source/blender/python/doc/examples/mathutils_vector.py
===================================================================
--- trunk/blender/source/blender/python/doc/examples/mathutils_vector.py 2010-02-28 11:54:48 UTC (rev 27186)
+++ trunk/blender/source/blender/python/doc/examples/mathutils_vector.py 2010-02-28 13:45:08 UTC (rev 27187)
@@ -1,55 +0,0 @@
-import Mathutils
-
-# zero length vector
-vec = Mathutils.Vector(0, 0, 1)
-
-# unit length vector
-vec_a = vec.copy().normalize()
-
-vec_b = Mathutils.Vector(0, 1, 2)
-
-vec2d = Mathutils.Vector(1, 2)
-vec3d = Mathutils.Vector([1, 0, 0])
-vec4d = vec_a.copy().resize4D()
-
-# other mathutuls types
-quat = Mathutils.Quaternion()
-matrix = Mathutils.Matrix()
-
-# Comparison operators can be done on Vector classes:
-
-# greater and less then test vector length.
-vec_a > vec_b
-vec_a >= vec_b
-vec_a < vec_b
-vec_a <= vec_b
-
-# ==, != test vector values e.g. 1,2,3 != 3,2,1 even if they are the same length
-vec_a == vec_b
-vec_a != vec_b
-
-
-# Math can be performed on Vector classes
-vec_a + vec_b
-vec_a - vec_b
-vec_a * vec_b
-vec_a * 10.0
-vec_a * matrix
-vec_a * vec_b
-vec_a * quat
--vec_a
-
-
-# You can access a vector object like a sequence
-x = vec_a[0]
-len(vec)
-vec_a[:] = vec_b
-vec2d[:] = vec3d[:2]
-
-
-# Vectors support 'swizzle' operations
-# See http://en.wikipedia.org/wiki/Swizzling_(computer_graphics)
-vec.xyz = vec.zyx
-vec.xy = vec4d.zw
-vec.xyz = vec4d.wzz
-vec4d.wxyz = vec.yxyx
Modified: trunk/blender/source/blender/python/doc/sphinx_doc_gen.py
===================================================================
--- trunk/blender/source/blender/python/doc/sphinx_doc_gen.py 2010-02-28 11:54:48 UTC (rev 27186)
+++ trunk/blender/source/blender/python/doc/sphinx_doc_gen.py 2010-02-28 13:45:08 UTC (rev 27187)
@@ -43,6 +43,9 @@
import rna_info
reload(rna_info)
+EXAMPLE_SET = set()
+EXAMPLE_SET_USED = set()
+
def range_str(val):
if val < -10000000: return '-inf'
if val > 10000000: return 'inf'
@@ -51,6 +54,16 @@
else:
return str(val)
+
+def write_example_ref(ident, fw, example_id, ext=".py"):
+ if example_id in EXAMPLE_SET:
+ fw("%s.. literalinclude:: ../examples/%s%s\n\n" % (ident, example_id, ext))
+ EXAMPLE_SET_USED.add(example_id)
+ else:
+ if bpy.app.debug:
+ print("\tskipping example:", example_id)
+
+
def write_indented_lines(ident, fn, text, strip=True):
if text is None:
return
@@ -152,6 +165,8 @@
# Note, may contain sphinx syntax, dont mangle!
fw(module.__doc__.strip())
fw("\n\n")
+
+ write_example_ref("", fw, module_name)
# write members of the module
# only tested with PyStructs which are not exactly modules
@@ -188,6 +203,7 @@
if value.__doc__:
write_indented_lines(" ", fw, value.__doc__, False)
fw("\n")
+ write_example_ref(" ", fw, module_name + "." + attribute)
for key in sorted(value.__dict__.keys()):
if key.startswith("__"):
@@ -197,6 +213,7 @@
if descr.__doc__:
fw(" .. attribute:: %s\n\n" % key)
write_indented_lines(" ", fw, descr.__doc__, False)
+ write_example_ref(" ", fw, module_name + "." + attribute + "." + key)
fw("\n")
for key in sorted(value.__dict__.keys()):
@@ -206,6 +223,7 @@
if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
if descr.__doc__:
write_indented_lines(" ", fw, descr.__doc__, False)
+ write_example_ref(" ", fw, module_name + "." + attribute + "." + key)
fw("\n")
fw("\n\n")
@@ -501,14 +519,27 @@
path_in = 'source/blender/python/doc/sphinx-in'
path_out = 'source/blender/python/doc/sphinx-in'
+ path_examples = 'source/blender/python/doc/examples'
shutil.rmtree(path_in, True)
shutil.rmtree(path_out, True)
+
+ for f in os.listdir(path_examples):
+ if f.endswith(".py"):
+ EXAMPLE_SET.add(os.path.splitext(f)[0])
+
rna2sphinx(path_in)
# for fast module testing
# os.system("rm source/blender/python/doc/sphinx-in/bpy.types.*.rst")
# os.system("rm source/blender/python/doc/sphinx-in/bpy.ops.*.rst")
+
+ EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list