archive/blender-archive
Archived
1
1
Fork 0
Code Pull Requests Packages Activity

Merged changes in the trunk up to revision 34670.

Browse Source
This commit is contained in:
Tamito Kajiyama
2011-02-06 18:05:05 +00:00
parent 949a752ddd 0ea9271f43
commit 5ed1597e26
232 changed files with 4940 additions and 3106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/python_api/examples/mathutils.Vector.py
View File

@@ -10,7 +10,7 @@ vec_b = mathutils.Vector((0, 1, 2))
vec2d = mathutils.Vector((1, 2))
vec3d = mathutils.Vector((1, 0, 0))
vec4d = vec_a.copy().resize4D()
vec4d = vec_a.to_4d()
# other mathutuls types
quat = mathutils.Quaternion()

8
doc/python_api/examples/mathutils.py
View File

@@ -3,15 +3,15 @@ from math import radians
vec = mathutils.Vector((1.0, 2.0, 3.0))
mat_rot = mathutils.Matrix.Rotation(radians(90), 4, 'X')
mat_rot = mathutils.Matrix.Rotation(radians(90.0), 4, 'X')
mat_trans = mathutils.Matrix.Translation(vec)
mat = mat_trans * mat_rot
mat.invert()
mat3 = mat.rotation_part()
quat1 = mat.to_quat()
quat2 = mat3.to_quat()
mat3 = mat.to_3x3()
quat1 = mat.to_quaternion()
quat2 = mat3.to_quaternion()
angle = quat1.difference(quat2)

163
doc/python_api/sphinx_doc_gen.py
View File

@@ -18,6 +18,8 @@
#
# #**** END GPL LICENSE BLOCK #****
# <pep8 compliant>
script_help_msg = '''
Usage:
@@ -31,11 +33,11 @@ For HTML generation
assuming that ./blender.bin is or links to the blender executable
- Generate html docs by running...
sphinx-build doc/python_api/sphinx-in doc/python_api/sphinx-out
assuming that you have sphinx 0.6.7 installed
For PDF generation
------------------
- After you have built doc/python_api/sphinx-in (see above), run:
@@ -82,10 +84,12 @@ def range_str(val):
Converts values to strings for the range directive.
(unused function it seems)
'''
if val < -10000000: return '-inf'
if val > 10000000: return 'inf'
if type(val)==float:
return '%g' % val
if val < -10000000:
return '-inf'
elif val > 10000000:
return 'inf'
elif type(val) == float:
return '%g' % val
else:
return str(val)
@@ -140,7 +144,7 @@ def pyfunc2sphinx(ident, fw, identifier, py_func, is_class=True):
if not is_class:
func_type = "function"
# ther rest are class methods
elif arg_str.startswith("(self, "):
arg_str = "(" + arg_str[7:]
@@ -157,14 +161,14 @@ def pyfunc2sphinx(ident, fw, identifier, py_func, is_class=True):
fw("\n")
def py_descr2sphinx(ident, fw, descr, module_name, type_name, identifier):
def py_descr2sphinx(ident, fw, descr, module_name, type_name, identifier):
if identifier.startswith("_"):
return
doc = descr.__doc__
if not doc:
doc = undocumented_message(module_name, type_name, identifier)
if type(descr) == GetSetDescriptorType:
fw(ident + ".. attribute:: %s\n\n" % identifier)
write_indented_lines(ident + " ", fw, doc, False)
@@ -181,7 +185,7 @@ def py_c_func2sphinx(ident, fw, module_name, type_name, identifier, py_func, is_
'''
c defined function to sphinx.
'''
# dump the docstring, assume its formatted correctly
if py_func.__doc__:
write_indented_lines(ident, fw, py_func.__doc__, False)
@@ -209,30 +213,30 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
import types
attribute_set = set()
filepath = os.path.join(BASEPATH, module_name + ".rst")
file = open(filepath, "w")
fw = file.write
fw(title + "\n")
fw(("=" * len(title)) + "\n\n")
fw(".. module:: %s\n\n" % module_name)
if module.__doc__:
# 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
for key, descr in sorted(type(module).__dict__.items()):
if key.startswith("__"):
continue
# naughty, we also add getset's into PyStructs, this is not typical py but also not incorrect.
if type(descr) == types.GetSetDescriptorType: # 'bpy_app_type' name is only used for examples and messages
if type(descr) == types.GetSetDescriptorType: # 'bpy_app_type' name is only used for examples and messages
py_descr2sphinx("", fw, descr, module_name, "bpy_app_type", key)
attribute_set.add(key)
for key, descr in sorted(type(module).__dict__.items()):
@@ -246,7 +250,7 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
attribute_set.add(key)
fw("\n")
del key, descr
classes = []
for attribute in sorted(dir(module)):
@@ -255,16 +259,16 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
if attribute in attribute_set:
continue
if attribute.startswith("n_"): # annoying exception, needed for bpy.app
if attribute.startswith("n_"): # annoying exception, needed for bpy.app
continue
value = getattr(module, attribute)
value_type = type(value)
if value_type == types.FunctionType:
pyfunc2sphinx("", fw, attribute, value, is_class=False)
elif value_type in (types.BuiltinMethodType, types.BuiltinFunctionType): # both the same at the moment but to be future proof
elif value_type in (types.BuiltinMethodType, types.BuiltinFunctionType): # both the same at the moment but to be future proof
# note: can't get args from these, so dump the string as is
# this means any module used like this must have fully formatted docstrings.
py_c_func2sphinx("", fw, module_name, module, attribute, value, is_class=False)
@@ -317,7 +321,6 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
file.close()
def rna2sphinx(BASEPATH):
structs, funcs, ops, props = rna_info.BuildRNAInfo()
@@ -332,14 +335,13 @@ def rna2sphinx(BASEPATH):
file = open(filepath, "w")
fw = file.write
version_string = bpy.app.version_string.split("(")[0]
version_string = ".".join(str(v) for v in bpy.app.version)
if bpy.app.build_revision != "Unknown":
version_string = version_string + " r" + bpy.app.build_revision
# for use with files
version_string_fp = "_".join(str(v) for v in bpy.app.version)
fw("project = 'Blender'\n")
# fw("master_doc = 'index'\n")
fw("copyright = u'Blender Foundation'\n")
@@ -356,11 +358,11 @@ def rna2sphinx(BASEPATH):
fw("latex_paper_size = 'a4paper'\n")
file.close()
# main page needed for sphinx (index.html)
filepath = os.path.join(BASEPATH, "contents.rst")
file = open(filepath, "w")
fw = file.write
fw("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n")
fw(" Blender Documentation contents\n")
fw("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n")
@@ -395,15 +397,15 @@ def rna2sphinx(BASEPATH):
fw("\n")
fw(".. toctree::\n")
fw(" :maxdepth: 1\n\n")
fw(" bpy.data.rst\n\n") # note: not actually a module
fw(" bpy.data.rst\n\n") # note: not actually a module
fw(" bpy.ops.rst\n\n")
fw(" bpy.types.rst\n\n")
# py modules
fw(" bpy.utils.rst\n\n")
fw(" bpy.path.rst\n\n")
fw(" bpy.app.rst\n\n")
# C modules
fw(" bpy.props.rst\n\n")
@@ -414,7 +416,6 @@ def rna2sphinx(BASEPATH):
fw(".. toctree::\n")
fw(" :maxdepth: 1\n\n")
fw(" mathutils.rst\n\n")
fw(" Freestyle.rst\n\n")
fw(" mathutils.geometry.rst\n\n")
@@ -422,7 +423,7 @@ def rna2sphinx(BASEPATH):
#fw(" bgl.rst\n\n")
fw(" blf.rst\n\n")
fw(" aud.rst\n\n")
# game engine
fw("===================\n")
fw("Game Engine Modules\n")
@@ -437,7 +438,6 @@ def rna2sphinx(BASEPATH):
file.close()
# internal modules
filepath = os.path.join(BASEPATH, "bpy.ops.rst")
file = open(filepath, "w")
@@ -459,7 +459,6 @@ def rna2sphinx(BASEPATH):
fw(" bpy.types.*\n\n")
file.close()
# not actually a module, only write this file so we
# can reference in the TOC
filepath = os.path.join(BASEPATH, "bpy.data.rst")
@@ -482,7 +481,6 @@ def rna2sphinx(BASEPATH):
EXAMPLE_SET_USED.add("bpy.data")
# python modules
from bpy import utils as module
pymodule2sphinx(BASEPATH, "bpy.utils", module, "Utilities (bpy.utils)")
@@ -496,7 +494,7 @@ def rna2sphinx(BASEPATH):
from bpy import props as module
pymodule2sphinx(BASEPATH, "bpy.props", module, "Property Definitions (bpy.props)")
import mathutils as module
pymodule2sphinx(BASEPATH, "mathutils", module, "Math Types & Utilities (mathutils)")
del module
@@ -512,7 +510,7 @@ def rna2sphinx(BASEPATH):
import blf as module
pymodule2sphinx(BASEPATH, "blf", module, "Font Drawing (blf)")
del module
# XXX TODO
#import bgl as module
#pymodule2sphinx(BASEPATH, "bgl", module, "Blender OpenGl wrapper (bgl)")
@@ -525,17 +523,16 @@ def rna2sphinx(BASEPATH):
## game engine
import shutil
# copy2 keeps time/date stamps
shutil.copy2(os.path.join(BASEPATH,"..","rst","bge.types.rst"), BASEPATH)
shutil.copy2(os.path.join(BASEPATH,"..","rst","bge.logic.rst"), BASEPATH)
shutil.copy2(os.path.join(BASEPATH,"..","rst","bge.render.rst"), BASEPATH)
shutil.copy2(os.path.join(BASEPATH,"..","rst","bge.events.rst"), BASEPATH)
shutil.copy2(os.path.join(BASEPATH, "..", "rst", "bge.types.rst"), BASEPATH)
shutil.copy2(os.path.join(BASEPATH, "..", "rst", "bge.logic.rst"), BASEPATH)
shutil.copy2(os.path.join(BASEPATH, "..", "rst", "bge.render.rst"), BASEPATH)
shutil.copy2(os.path.join(BASEPATH, "..", "rst", "bge.events.rst"), BASEPATH)
if 0:
filepath = os.path.join(BASEPATH, "bpy.rst")
file = open(filepath, "w")
fw = file.write
fw("\n")
title = ":mod:`bpy` --- Blender Python Module"
@@ -570,7 +567,7 @@ def rna2sphinx(BASEPATH):
filepath = os.path.join(BASEPATH, "bpy.types.%s.rst" % struct.identifier)
file = open(filepath, "w")
fw = file.write
base_id = getattr(struct.base, "identifier", "")
if _BPY_STRUCT_FAKE:
@@ -583,16 +580,16 @@ def rna2sphinx(BASEPATH):
title = struct.identifier
fw("%s\n%s\n\n" % (title, "=" * len(title)))
fw(".. module:: bpy.types\n\n")
base_ids = [base.identifier for base in struct.get_bases()]
if _BPY_STRUCT_FAKE:
base_ids.append(_BPY_STRUCT_FAKE)
base_ids.reverse()
if base_ids:
if len(base_ids) > 1:
fw("base classes --- ")
@@ -601,13 +598,13 @@ def rna2sphinx(BASEPATH):
fw(", ".join((":class:`%s`" % base_id) for base_id in base_ids))
fw("\n\n")
subclass_ids = [s.identifier for s in structs.values() if s.base is struct if not rna_info.rna_id_ignore(s.identifier)]
if subclass_ids:
fw("subclasses --- \n" + ", ".join((":class:`%s`" % s) for s in subclass_ids) + "\n\n")
base_id = getattr(struct.base, "identifier", "")
if _BPY_STRUCT_FAKE:
if not base_id:
base_id = _BPY_STRUCT_FAKE
@@ -618,7 +615,7 @@ def rna2sphinx(BASEPATH):
fw(".. class:: %s\n\n" % struct.identifier)
fw(" %s\n\n" % struct.description)
# properties sorted in alphabetical order
sorted_struct_properties = struct.properties[:]
sorted_struct_properties.sort(key=lambda prop: prop.identifier)
@@ -633,7 +630,7 @@ def rna2sphinx(BASEPATH):
if prop.description:
fw(" %s\n\n" % prop.description)
fw(" :type: %s\n\n" % type_descr)
# python attributes
py_properties = struct.get_py_properties()
py_prop = None
@@ -646,13 +643,13 @@ def rna2sphinx(BASEPATH):
fw(" .. %s:: %s(%s)\n\n" % ("classmethod" if func.is_classmethod else "method", func.identifier, args_str))
fw(" %s\n\n" % func.description)
for prop in func.args:
write_param(" ", fw, prop)
if len(func.return_values) == 1:
write_param(" ", fw, func.return_values[0], is_return=True)
elif func.return_values: # multiple return values
elif func.return_values: # multiple return values
fw(" :return (%s):\n" % ", ".join(prop.identifier for prop in func.return_values))
for prop in func.return_values:
type_descr = prop.get_type_description(as_ret=True, class_fmt=":class:`%s`")
@@ -663,11 +660,10 @@ def rna2sphinx(BASEPATH):
fw("\n")
# python methods
py_funcs = struct.get_py_functions()
py_func = None
for identifier, py_func in py_funcs:
pyfunc2sphinx(" ", fw, identifier, py_func, is_class=True)
del py_funcs, py_func
@@ -679,10 +675,10 @@ def rna2sphinx(BASEPATH):
# props
lines[:] = []
if _BPY_STRUCT_FAKE:
descr_items = [(key, descr) for key, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()) if not key.startswith("__")]
if _BPY_STRUCT_FAKE:
for key, descr in descr_items:
if type(descr) == GetSetDescriptorType:
@@ -694,10 +690,10 @@ def rna2sphinx(BASEPATH):
for identifier, py_prop in base.get_py_properties():
lines.append(" * :class:`%s.%s`\n" % (base.identifier, identifier))
for identifier, py_prop in base.get_py_properties():
lines.append(" * :class:`%s.%s`\n" % (base.identifier, identifier))
if lines:
fw(".. rubric:: Inherited Properties\n\n")
@@ -708,7 +704,6 @@ def rna2sphinx(BASEPATH):
fw(line)
fw("\n")
# funcs
lines[:] = []
@@ -732,9 +727,8 @@ def rna2sphinx(BASEPATH):
for line in lines:
fw(line)
fw("\n")
lines[:] = []
lines[:] = []
if struct.references:
# use this otherwise it gets in the index for a normal heading.
@@ -750,13 +744,12 @@ def rna2sphinx(BASEPATH):
fw(" * :class:`%s`\n" % ref)
fw("\n")
for struct in structs.values():
# TODO, rna_info should filter these out!
if "_OT_" in struct.identifier:
continue
write_struct(struct)
# special case, bpy_struct
if _BPY_STRUCT_FAKE:
filepath = os.path.join(BASEPATH, "bpy.types.%s.rst" % _BPY_STRUCT_FAKE)
@@ -781,41 +774,40 @@ def rna2sphinx(BASEPATH):
descr_items = [(key, descr) for key, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()) if not key.startswith("__")]
for key, descr in descr_items:
if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
py_descr2sphinx(" ", fw, descr, "bpy.types", _BPY_STRUCT_FAKE, key)
for key, descr in descr_items:
if type(descr) == GetSetDescriptorType:
py_descr2sphinx(" ", fw, descr, "bpy.types", _BPY_STRUCT_FAKE, key)
# operators
def write_ops():
API_BASEURL='https://svn.blender.org/svnroot/bf-blender/trunk/blender/release/scripts'
API_BASEURL = "https://svn.blender.org/svnroot/bf-blender/trunk/blender/release/scripts"
fw = None
last_mod = ''
for op_key in sorted(ops.keys()):
op = ops[op_key]
if last_mod != op.module_name:
filepath = os.path.join(BASEPATH, "bpy.ops.%s.rst" % op.module_name)
file = open(filepath, "w")
fw = file.write
title = "%s Operators" % (op.module_name[0].upper() + op.module_name[1:])
title = "%s Operators" % (op.module_name[0].upper() + op.module_name[1:])
fw("%s\n%s\n\n" % (title, "=" * len(title)))
fw(".. module:: bpy.ops.%s\n\n" % op.module_name)
last_mod = op.module_name
args_str = ", ".join(prop.get_arg_default(force=True) for prop in op.args)
fw(".. function:: %s(%s)\n\n" % (op.func_name, args_str))
# if the description isn't valid, we output the standard warning
# if the description isn't valid, we output the standard warning
# with a link to the wiki so that people can help
if not op.description or op.description == "(undocumented operator)":
operator_description = undocumented_message('bpy.ops',op.module_name,op.func_name)
operator_description = undocumented_message('bpy.ops', op.module_name, op.func_name)
else:
operator_description = op.description
@@ -827,12 +819,13 @@ def rna2sphinx(BASEPATH):
location = op.get_location()
if location != (None, None):
fw(" :file: `%s <%s/%s>`_:%d\n\n" % (location[0],API_BASEURL,location[0],location[1]))
fw(" :file: `%s <%s/%s>`_:%d\n\n" % (location[0], API_BASEURL, location[0], location[1]))
write_ops()
file.close()
def main():
import bpy
if 'bpy' not in dir():
@@ -842,9 +835,9 @@ def main():
import shutil
script_dir = os.path.dirname(__file__)
path_in = os.path.join(script_dir,'sphinx-in')
path_out = os.path.join(script_dir,'sphinx-out')
path_examples = os.path.join(script_dir,'examples')
path_in = os.path.join(script_dir, "sphinx-in")
path_out = os.path.join(script_dir, "sphinx-out")
path_examples = os.path.join(script_dir, "examples")
# only for partial updates
path_in_tmp = path_in + "-tmp"
@@ -855,7 +848,6 @@ def main():
if f.endswith(".py"):
EXAMPLE_SET.add(os.path.splitext(f)[0])
# only for full updates
if _BPY_FULL_REBUILD:
shutil.rmtree(path_in, True)
@@ -872,7 +864,7 @@ def main():
# now move changed files from 'path_in_tmp' --> 'path_in'
file_list_path_in = set(os.listdir(path_in))
file_list_path_in_tmp = set(os.listdir(path_in_tmp))
# remove deprecated files that have been removed.
for f in sorted(file_list_path_in):
if f not in file_list_path_in_tmp:
@@ -888,14 +880,13 @@ def main():
if f in file_list_path_in:
if filecmp.cmp(f_from, f_to):
do_copy = False
if do_copy:
print("\tupdating: %s" % f)
shutil.copy(f_from, f_to)
'''else:
print("\tkeeping: %s" % f) # eh, not that useful'''
EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED
if EXAMPLE_SET_UNUSED:
print("\nUnused examples found in '%s'..." % path_examples)

15
doc/python_api/sphinx_doc_gen.sh
View File

@@ -4,10 +4,11 @@
# ssh upload means you need an account on the server
BLENDER="./blender.bin"
SSH_HOST="ideasman42@emo.blender.org"
SSH_USER="ideasman42"
SSH_HOST=$SSH_USER"@emo.blender.org"
SSH_UPLOAD="/data/www/vhosts/www.blender.org/documentation" # blender_python_api_VERSION, added after
# sed string from hell, 'Blender 2.53 (sub 1) Build' --> '2_53_1'
# 'Blender 2.53 (sub 1) Build' --> '2_53_1' as a shell script.
# "_".join(str(v) for v in bpy.app.version)
# custom blender vars
blender_srcdir=$(dirname $0)/../../
@@ -25,12 +26,18 @@ $BLENDER --background --factory-startup --python $SPHINXBASE/sphinx_doc_gen.py
# html
sphinx-build $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out
cp $SPHINXBASE/sphinx-out/contents.html $SPHINXBASE/sphinx-out/index.html
ssh ideasman42@emo.blender.org 'rm -rf '$SSH_UPLOAD_FULL'/*'
ssh $SSH_USER@emo.blender.org 'rm -rf '$SSH_UPLOAD_FULL'/*'
rsync --progress -avze "ssh -p 22" $SPHINXBASE/sphinx-out/* $SSH_HOST:$SSH_UPLOAD_FULL/
# symlink the dir to a static URL
ssh $SSH_USER@emo.blender.org 'rm '$SSH_UPLOAD'/250PythonDoc && ln -s '$SSH_UPLOAD_FULL' '$SSH_UPLOAD'/250PythonDoc'
# pdf
sphinx-build -b latex $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out
cd $SPHINXBASE/sphinx-out
make
cd -
rsync --progress -avze "ssh -p 22" $SPHINXBASE/sphinx-out/contents.pdf $SSH_HOST:$SSH_UPLOAD_FULL/blender_python_reference_$BLENDER_VERSION.pdf
# rename so local PDF has matching name.
mv $SPHINXBASE/sphinx-out/contents.pdf $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf
rsync --progress -avze "ssh -p 22" $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf $SSH_HOST:$SSH_UPLOAD_FULL/blender_python_reference_$BLENDER_VERSION.pdf