2009-12-25 16:50:53 +01:00
# ***** 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,
2010-02-12 14:34:04 +01:00
# Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2009-12-25 16:50:53 +01:00
#
# Contributor(s): Campbell Barton
#
# #**** END GPL LICENSE BLOCK #****
script_help_msg = '''
2010-10-13 12:42:33 +02:00
Usage :
2009-12-25 16:50:53 +01:00
2010-10-13 12:42:33 +02:00
For HTML generation
- - - - - - - - - - - - - - - - - - -
- Run this script from blenders root path once you have compiled blender
. / blender . bin - b - P doc / python_api / sphinx_doc_gen . py
2010-01-28 11:48:17 +01:00
2010-10-13 12:42:33 +02:00
This will generate python files in doc / python_api / sphinx - in / ,
assuming that . / blender . bin is or links to the blender executable
2010-01-28 11:48:17 +01:00
2010-10-13 12:42:33 +02:00
- 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
2010-01-28 11:48:17 +01:00
For PDF generation
2010-10-13 12:42:33 +02:00
- - - - - - - - - - - - - - - - - -
- After you have built doc / python_api / sphinx - in ( see above ) , run :
2010-01-28 11:48:17 +01:00
2010-10-13 12:42:33 +02:00
sphinx - build - b latex doc / python_api / sphinx - in doc / python_api / sphinx - out
cd doc / python_api / sphinx - out
2010-01-28 11:48:17 +01:00
make
2009-12-25 16:50:53 +01:00
'''
2010-05-30 02:24:32 +02:00
# import rpdb2; rpdb2.start_embedded_debugger('test')
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
2009-12-25 16:50:53 +01:00
import os
2009-12-26 17:47:25 +01:00
import inspect
2009-12-25 16:50:53 +01:00
import bpy
import rna_info
reload ( rna_info )
2010-04-06 00:37:09 +02:00
# lame, python wont give some access
2010-08-11 19:13:39 +02:00
ClassMethodDescriptorType = type ( dict . __dict__ [ ' fromkeys ' ] )
2010-04-06 00:37:09 +02:00
MethodDescriptorType = type ( dict . get )
GetSetDescriptorType = type ( int . real )
2010-02-28 14:45:08 +01:00
EXAMPLE_SET = set ( )
EXAMPLE_SET_USED = set ( )
2010-04-10 20:35:50 +02:00
_BPY_STRUCT_FAKE = " bpy_struct "
2010-05-03 17:52:15 +02:00
_BPY_FULL_REBUILD = False
2010-04-10 20:35:50 +02:00
2010-06-15 04:06:01 +02:00
def undocumented_message ( module_name , type_name , identifier ) :
message = " Undocumented (`contribute " \
" <http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute " \
2010-06-17 04:38:49 +02:00
" ?action=edit§ion=new&preload=Dev:2.5/Py/API/Documentation/Contribute/Howto-message " \
2010-06-15 04:06:01 +02:00
" &preloadtitle= %s . %s . %s >`_) \n \n " % ( module_name , type_name , identifier )
return message
2010-06-12 00:41:13 +02:00
2009-12-25 16:50:53 +01:00
def range_str ( val ) :
2010-06-15 04:06:01 +02:00
'''
Converts values to strings for the range directive .
( unused function it seems )
'''
2009-12-25 16:50:53 +01:00
if val < - 10000000 : return ' -inf '
if val > 10000000 : return ' inf '
if type ( val ) == float :
return ' %g ' % val
else :
return str ( val )
2010-02-28 14:45:08 +01:00
2010-06-15 04:06:01 +02:00
def write_example_ref ( ident , fw , example_id , ext = " py " ) :
2010-02-28 14:45:08 +01:00
if example_id in EXAMPLE_SET :
2010-06-15 04:06:01 +02:00
fw ( " %s .. literalinclude:: ../examples/ %s . %s \n \n " % ( ident , example_id , ext ) )
2010-02-28 14:45:08 +01:00
EXAMPLE_SET_USED . add ( example_id )
else :
if bpy . app . debug :
print ( " \t skipping example: " , example_id )
2010-01-31 22:52:26 +01:00
def write_indented_lines ( ident , fn , text , strip = True ) :
2010-06-15 04:06:01 +02:00
'''
Apply same indentation to all lines in a multilines text .
'''
2009-12-25 16:50:53 +01:00
if text is None :
return
for l in text . split ( " \n " ) :
2010-01-31 22:52:26 +01:00
if strip :
fn ( ident + l . strip ( ) + " \n " )
else :
fn ( ident + l + " \n " )
2009-12-25 16:50:53 +01:00
2010-01-22 03:04:25 +01:00
def pymethod2sphinx ( ident , fw , identifier , py_func ) :
'''
class method to sphinx
'''
arg_str = inspect . formatargspec ( * inspect . getargspec ( py_func ) )
if arg_str . startswith ( " (self, " ) :
arg_str = " ( " + arg_str [ 7 : ]
func_type = " method "
elif arg_str . startswith ( " (cls, " ) :
arg_str = " ( " + arg_str [ 6 : ]
func_type = " classmethod "
else :
func_type = " staticmethod "
fw ( ident + " .. %s :: %s %s \n \n " % ( func_type , identifier , arg_str ) )
if py_func . __doc__ :
write_indented_lines ( ident + " " , fw , py_func . __doc__ )
fw ( " \n " )
def pyfunc2sphinx ( ident , fw , identifier , py_func , is_class = True ) :
'''
function or class method to sphinx
'''
arg_str = inspect . formatargspec ( * inspect . getargspec ( py_func ) )
if not is_class :
func_type = " function "
# ther rest are class methods
elif arg_str . startswith ( " (self, " ) :
arg_str = " ( " + arg_str [ 7 : ]
func_type = " method "
elif arg_str . startswith ( " (cls, " ) :
arg_str = " ( " + arg_str [ 6 : ]
func_type = " classmethod "
else :
func_type = " staticmethod "
fw ( ident + " .. %s :: %s %s \n \n " % ( func_type , identifier , arg_str ) )
if py_func . __doc__ :
write_indented_lines ( ident + " " , fw , py_func . __doc__ . strip ( ) )
fw ( " \n " )
2010-04-10 20:35:50 +02:00
def py_descr2sphinx ( ident , fw , descr , module_name , type_name , identifier ) :
2010-07-19 15:36:10 +02:00
if identifier . startswith ( " _ " ) :
return
2010-04-10 20:35:50 +02:00
doc = descr . __doc__
if not doc :
2010-06-15 04:06:01 +02:00
doc = undocumented_message ( module_name , type_name , identifier )
2010-04-10 20:35:50 +02:00
if type ( descr ) == GetSetDescriptorType :
fw ( ident + " .. attribute:: %s \n \n " % identifier )
2010-05-30 02:24:32 +02:00
write_indented_lines ( ident + " " , fw , doc , False )
2010-08-11 19:13:39 +02:00
elif type ( descr ) in ( MethodDescriptorType , ClassMethodDescriptorType ) :
2010-04-10 20:35:50 +02:00
write_indented_lines ( ident , fw , doc , False )
else :
2010-08-11 19:13:39 +02:00
raise TypeError ( " type was not GetSetDescriptorType, MethodDescriptorType or ClassMethodDescriptorType " )
2010-04-10 20:35:50 +02:00
write_example_ref ( ident , fw , module_name + " . " + type_name + " . " + identifier )
fw ( " \n " )
2010-06-15 04:06:01 +02:00
def py_c_func2sphinx ( ident , fw , module_name , type_name , identifier , py_func , is_class = True ) :
2010-01-22 03:04:25 +01:00
'''
c defined function to sphinx .
'''
# dump the docstring, assume its formatted correctly
if py_func . __doc__ :
2010-01-31 22:52:26 +01:00
write_indented_lines ( ident , fw , py_func . __doc__ , False )
2010-01-22 03:04:25 +01:00
fw ( " \n " )
else :
fw ( ident + " .. function:: %s () \n \n " % identifier )
2010-06-15 04:06:01 +02:00
fw ( ident + " " + undocumented_message ( module_name , type_name , identifier ) )
2010-01-22 03:04:25 +01:00
def pyprop2sphinx ( ident , fw , identifier , py_prop ) :
'''
python property to sphinx
'''
2010-06-28 02:06:23 +02:00
# readonly properties use "data" directive, variables use "attribute" directive
if py_prop . fset is None :
fw ( ident + " .. data:: %s \n \n " % identifier )
else :
fw ( ident + " .. attribute:: %s \n \n " % identifier )
2010-01-22 03:04:25 +01:00
write_indented_lines ( ident + " " , fw , py_prop . __doc__ )
if py_prop . fset is None :
fw ( ident + " (readonly) \n \n " )
def pymodule2sphinx ( BASEPATH , module_name , module , title ) :
import types
2010-04-10 21:06:18 +02:00
attribute_set = set ( )
2010-01-22 03:04:25 +01:00
filepath = os . path . join ( BASEPATH , module_name + " .rst " )
file = open ( filepath , " w " )
2010-01-27 22:33:39 +01:00
2010-01-22 03:04:25 +01:00
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 " )
2010-02-28 14:45:08 +01:00
write_example_ref ( " " , fw , module_name )
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
2010-01-31 22:52:26 +01:00
# write members of the module
# only tested with PyStructs which are not exactly modules
2010-04-10 20:35:50 +02:00
for key , descr in sorted ( type ( module ) . __dict__ . items ( ) ) :
2010-01-31 22:52:26 +01:00
if type ( descr ) == types . MemberDescriptorType :
if descr . __doc__ :
2010-04-10 20:35:50 +02:00
fw ( " .. data:: %s \n \n " % key )
2010-01-31 22:52:26 +01:00
write_indented_lines ( " " , fw , descr . __doc__ , False )
2010-04-10 21:06:18 +02:00
attribute_set . add ( key )
2010-01-31 22:52:26 +01:00
fw ( " \n " )
2010-04-10 21:06:18 +02:00
del key , descr
2010-01-31 22:52:26 +01:00
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
classes = [ ]
2010-01-22 03:04:25 +01:00
2010-04-06 00:37:09 +02:00
for attribute in sorted ( dir ( module ) ) :
2010-01-22 03:04:25 +01:00
if not attribute . startswith ( " _ " ) :
2010-04-10 21:06:18 +02:00
if attribute in attribute_set :
continue
if attribute . startswith ( " n_ " ) : # annoying exception, needed for bpy.app
continue
2010-01-22 03:04:25 +01:00
value = getattr ( module , attribute )
value_type = type ( value )
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
2010-01-22 03:04:25 +01:00
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
# 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.
2010-06-15 04:06:01 +02:00
py_c_func2sphinx ( " " , fw , module_name , module , attribute , value , is_class = False )
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
elif value_type == type :
classes . append ( ( attribute , value ) )
2010-04-06 00:37:09 +02:00
elif value_type in ( bool , int , float , str , tuple ) :
# constant, not much fun we can do here except to list it.
# TODO, figure out some way to document these!
fw ( " .. data:: %s \n \n " % attribute )
write_indented_lines ( " " , fw , " constant value %s " % repr ( value ) , False )
fw ( " \n " )
else :
print ( " \t not documenting %s . %s " % ( module_name , attribute ) )
2010-04-10 21:06:18 +02:00
continue
attribute_set . add ( attribute )
2010-01-22 03:04:25 +01:00
# TODO, more types...
2010-04-10 20:35:50 +02:00
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
# write collected classes now
2010-04-10 20:35:50 +02:00
for ( type_name , value ) in classes :
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
# May need to be its own function
2010-04-10 20:35:50 +02:00
fw ( " .. class:: %s \n \n " % type_name )
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
if value . __doc__ :
2010-01-31 22:52:26 +01:00
write_indented_lines ( " " , fw , value . __doc__ , False )
2010-01-27 22:33:39 +01:00
fw ( " \n " )
2010-04-10 20:35:50 +02:00
write_example_ref ( " " , fw , module_name + " . " + type_name )
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
2010-04-10 20:35:50 +02:00
descr_items = [ ( key , descr ) for key , descr in sorted ( value . __dict__ . items ( ) ) if not key . startswith ( " __ " ) ]
2010-08-11 19:13:39 +02:00
for key , descr in descr_items :
2010-08-12 00:36:43 +02:00
if type ( descr ) == ClassMethodDescriptorType :
2010-08-11 19:13:39 +02:00
py_descr2sphinx ( " " , fw , descr , module_name , type_name , key )
2010-04-10 20:35:50 +02:00
for key , descr in descr_items :
2010-08-12 00:36:43 +02:00
if type ( descr ) == MethodDescriptorType :
2010-04-10 20:35:50 +02:00
py_descr2sphinx ( " " , fw , descr , module_name , type_name , key )
for key , descr in descr_items :
if type ( descr ) == GetSetDescriptorType :
py_descr2sphinx ( " " , fw , descr , module_name , type_name , key )
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
fw ( " \n \n " )
2010-01-22 03:04:25 +01:00
file . close ( )
2010-01-31 22:52:26 +01:00
2009-12-25 16:50:53 +01:00
def rna2sphinx ( BASEPATH ) :
structs , funcs , ops , props = rna_info . BuildRNAInfo ( )
try :
os . mkdir ( BASEPATH )
except :
pass
# conf.py - empty for now
filepath = os . path . join ( BASEPATH , " conf.py " )
file = open ( filepath , " w " )
fw = file . write
2010-03-01 11:34:54 +01:00
2010-01-31 22:52:26 +01:00
version_string = bpy . app . version_string . split ( " ( " ) [ 0 ]
if bpy . app . build_revision != " Unknown " :
version_string = version_string + " r " + bpy . app . build_revision
2010-09-03 11:21:40 +02:00
# for use with files
version_string_fp = " _ " . join ( str ( v ) for v in bpy . app . version )
2010-06-27 20:34:27 +02:00
fw ( " project = ' Blender ' \n " )
2009-12-25 16:50:53 +01:00
# fw("master_doc = 'index'\n")
fw ( " copyright = u ' Blender Foundation ' \n " )
2010-03-01 11:34:54 +01:00
fw ( " version = ' %s - UNSTABLE API ' \n " % version_string )
fw ( " release = ' %s - UNSTABLE API ' \n " % version_string )
2010-05-14 12:21:57 +02:00
fw ( " html_theme = ' blender-org ' \n " )
fw ( " html_theme_path = [ ' ../ ' ] \n " )
fw ( " html_favicon = ' favicon.ico ' \n " )
2010-03-01 11:34:54 +01:00
# not helpful since the source us generated, adds to upload size.
fw ( " html_copy_source = False \n " )
2010-01-28 11:48:17 +01:00
fw ( " \n " )
# needed for latex, pdf gen
fw ( " latex_documents = [ ( ' contents ' , ' contents.tex ' , ' Blender Index ' , ' Blender Foundation ' , ' manual ' ), ] \n " )
fw ( " latex_paper_size = ' a4paper ' \n " )
2009-12-25 16:50:53 +01:00
file . close ( )
filepath = os . path . join ( BASEPATH , " contents.rst " )
file = open ( filepath , " w " )
fw = file . write
2010-01-27 23:17:27 +01:00
fw ( " %% %% %% %% %% %% %% %% %% %% %% %% %% %% %% %% % \n " )
fw ( " Blender Documentation contents \n " )
fw ( " %% %% %% %% %% %% %% %% %% %% %% %% %% %% %% %% % \n " )
fw ( " \n " )
2010-01-31 22:52:26 +01:00
fw ( " This document is an API reference for Blender %s . built %s . \n " % ( version_string , bpy . app . build_date ) )
2010-01-27 23:17:27 +01:00
fw ( " \n " )
2010-06-27 20:34:27 +02:00
fw ( " An introduction to Blender and Python can be found at <http://wiki.blender.org/index.php/Dev:2.5/Py/API/Intro> \n " )
2009-12-25 16:50:53 +01:00
fw ( " \n " )
2010-09-03 11:21:40 +02:00
fw ( " `A PDF version of this document is also available <blender_python_reference_ %s .pdf>`__ \n " % version_string_fp )
merge own commits into render branch into trunk since 27560
27562, 27570, 27571, 27574, 27576, 27577, 27579, 27590, 27591, 27594, 27595, 27596, 27599, 27605, 27611, 27612, 27613, 27614, 27623
2010-03-20 17:41:01 +01:00
fw ( " \n " )
2010-03-01 11:34:54 +01:00
fw ( " .. warning:: The Python API in Blender is **UNSTABLE**, It should only be used for testing, any script written now may break in future releases. \n " )
fw ( " \n " )
fw ( " The following areas are subject to change. \n " )
fw ( " * operator names and arguments \n " )
2010-06-15 14:06:30 +02:00
fw ( " * render api \n " )
2010-03-01 11:34:54 +01:00
fw ( " * function calls with the data api (any function calls with values accessed from bpy.data), including functions for importing and exporting meshes \n " )
fw ( " * class registration (Operator, Panels, Menus, Headers) \n " )
fw ( " * modules: bpy.props, blf) \n " )
fw ( " * members in the bpy.context have to be reviewed \n " )
fw ( " * python defined modal operators, especially drawing callbacks are highly experemental \n " )
fw ( " \n " )
fw ( " These parts of the API are relatively stable and are unlikely to change significantly \n " )
fw ( " * data API, access to attributes of blender data such as mesh verts, material color, timeline frames and scene objects \n " )
fw ( " * user interface functions for defining buttons, creation of menus, headers, panels \n " )
2010-10-26 00:44:01 +02:00
fw ( " * modules: bgl and mathutils \n " )
2010-08-17 15:14:41 +02:00
fw ( " * game engine modules \n " )
2010-03-01 11:34:54 +01:00
fw ( " \n " )
2010-05-17 22:38:54 +02:00
fw ( " =================== \n " )
fw ( " Application Modules \n " )
fw ( " =================== \n " )
fw ( " \n " )
2009-12-25 16:50:53 +01:00
fw ( " .. toctree:: \n " )
2010-01-27 23:17:27 +01:00
fw ( " :maxdepth: 1 \n \n " )
2010-06-27 20:34:27 +02:00
fw ( " bpy.data.rst \n \n " ) # note: not actually a module
2010-01-27 23:17:27 +01:00
fw ( " bpy.ops.rst \n \n " )
fw ( " bpy.types.rst \n \n " )
2010-01-22 03:04:25 +01:00
# py modules
2010-01-27 23:17:27 +01:00
fw ( " bpy.utils.rst \n \n " )
2010-08-06 03:40:54 +02:00
fw ( " bpy.path.rst \n \n " )
2010-01-27 23:17:27 +01:00
fw ( " bpy.app.rst \n \n " )
2010-01-22 03:04:25 +01:00
# C modules
2010-01-27 23:17:27 +01:00
fw ( " bpy.props.rst \n \n " )
2010-05-17 22:38:54 +02:00
fw ( " ================== \n " )
fw ( " Standalone Modules \n " )
fw ( " ================== \n " )
fw ( " \n " )
fw ( " .. toctree:: \n " )
fw ( " :maxdepth: 1 \n \n " )
2010-04-11 16:22:27 +02:00
fw ( " mathutils.rst \n \n " )
2010-03-01 11:34:54 +01:00
fw ( " blf.rst \n \n " )
2010-07-16 23:42:20 +02:00
fw ( " aud.rst \n \n " )
2010-05-17 22:38:54 +02:00
# game engine
fw ( " =================== \n " )
fw ( " Game Engine Modules \n " )
fw ( " =================== \n " )
fw ( " \n " )
fw ( " .. toctree:: \n " )
fw ( " :maxdepth: 1 \n \n " )
fw ( " bge.types.rst \n \n " )
fw ( " bge.logic.rst \n \n " )
fw ( " bge.render.rst \n \n " )
fw ( " bge.events.rst \n \n " )
2010-01-27 23:17:27 +01:00
file . close ( )
# internal modules
filepath = os . path . join ( BASEPATH , " bpy.ops.rst " )
file = open ( filepath , " w " )
fw = file . write
2010-06-27 20:34:27 +02:00
fw ( " Operators (bpy.ops) \n " )
fw ( " =================== \n \n " )
2010-01-27 23:17:27 +01:00
fw ( " .. toctree:: \n " )
fw ( " :glob: \n \n " )
fw ( " bpy.ops.* \n \n " )
file . close ( )
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
2010-01-27 23:17:27 +01:00
filepath = os . path . join ( BASEPATH , " bpy.types.rst " )
file = open ( filepath , " w " )
fw = file . write
2010-06-27 20:34:27 +02:00
fw ( " Types (bpy.types) \n " )
fw ( " ================= \n \n " )
2010-01-27 23:17:27 +01:00
fw ( " .. toctree:: \n " )
fw ( " :glob: \n \n " )
fw ( " bpy.types.* \n \n " )
2009-12-25 16:50:53 +01:00
file . close ( )
2010-01-27 23:17:27 +01:00
2010-06-27 20:34:27 +02:00
# not actually a module, only write this file so we
# can reference in the TOC
filepath = os . path . join ( BASEPATH , " bpy.data.rst " )
file = open ( filepath , " w " )
fw = file . write
fw ( " Data Access (bpy.data) \n " )
fw ( " ====================== \n \n " )
fw ( " .. module:: bpy \n " )
fw ( " \n " )
fw ( " This module is used for all blender/python access. \n " )
fw ( " \n " )
2010-06-28 02:06:23 +02:00
fw ( " .. data:: data \n " )
2010-06-27 20:34:27 +02:00
fw ( " \n " )
fw ( " Access to blenders internal data \n " )
fw ( " \n " )
2010-09-03 16:53:54 +02:00
fw ( " :type: :class:`bpy.types.BlendData` \n " )
2010-11-25 15:55:03 +01:00
fw ( " \n " )
fw ( " .. literalinclude:: ../examples/bpy.data.py \n " )
2010-06-27 20:34:27 +02:00
file . close ( )
EXAMPLE_SET_USED . add ( " bpy.data " )
2010-01-22 03:04:25 +01:00
# python modules
from bpy import utils as module
2010-01-27 23:17:27 +01:00
pymodule2sphinx ( BASEPATH , " bpy.utils " , module , " Utilities (bpy.utils) " )
2010-01-31 22:52:26 +01:00
2010-08-06 03:40:54 +02:00
from bpy import path as module
pymodule2sphinx ( BASEPATH , " bpy.path " , module , " Path Utilities (bpy.path) " )
2010-01-31 22:52:26 +01:00
# C modules
2010-01-22 03:04:25 +01:00
from bpy import app as module
2010-01-27 23:17:27 +01:00
pymodule2sphinx ( BASEPATH , " bpy.app " , module , " Application Data (bpy.app) " )
2010-01-22 03:04:25 +01:00
from bpy import props as module
2010-01-27 23:17:27 +01:00
pymodule2sphinx ( BASEPATH , " bpy.props " , module , " Property Definitions (bpy.props) " )
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
2010-04-11 16:22:27 +02:00
import mathutils as module
pymodule2sphinx ( BASEPATH , " mathutils " , module , " Math Types & Utilities (mathutils) " )
2010-01-22 03:04:25 +01:00
del module
2010-03-01 11:34:54 +01:00
import blf as module
2010-06-27 20:34:27 +02:00
pymodule2sphinx ( BASEPATH , " blf " , module , " Font Drawing (blf) " )
2010-02-28 12:54:48 +01:00
del module
2010-07-16 23:42:20 +02:00
import aud as module
pymodule2sphinx ( BASEPATH , " aud " , module , " Audio System (aud) " )
del module
2010-01-27 23:17:27 +01:00
2010-10-13 12:42:33 +02:00
## game engine
2010-05-17 22:38:54 +02:00
import shutil
# copy2 keeps time/date stamps
2010-10-13 12:42:33 +02:00
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 )
2010-05-17 22:38:54 +02:00
2009-12-25 16:50:53 +01:00
if 0 :
filepath = os . path . join ( BASEPATH , " bpy.rst " )
file = open ( filepath , " w " )
fw = file . write
fw ( " \n " )
title = " :mod:`bpy` --- Blender Python Module "
fw ( " %s \n %s \n \n " % ( title , " = " * len ( title ) ) )
fw ( " .. module:: bpy.types \n \n " )
file . close ( )
2009-12-26 17:47:25 +01:00
def write_param ( ident , fw , prop , is_return = False ) :
if is_return :
id_name = " return "
id_type = " rtype "
2010-01-18 11:45:54 +01:00
kwargs = { " as_ret " : True , " class_fmt " : " :class:` %s ` " }
identifier = " "
2009-12-25 16:50:53 +01:00
else :
2009-12-26 17:47:25 +01:00
id_name = " arg "
id_type = " type "
2010-01-18 11:45:54 +01:00
kwargs = { " as_arg " : True , " class_fmt " : " :class:` %s ` " }
identifier = " %s " % prop . identifier
2009-12-25 16:50:53 +01:00
2010-01-18 11:45:54 +01:00
type_descr = prop . get_type_description ( * * kwargs )
2009-12-26 17:47:25 +01:00
if prop . name or prop . description :
2010-09-19 09:07:14 +02:00
fw ( ident + " : %s %s : %s \n " % ( id_name , identifier , " , " . join ( val for val in ( prop . name , prop . description ) if val ) ) )
2010-01-18 11:45:54 +01:00
fw ( ident + " : %s %s : %s \n " % ( id_type , identifier , type_descr ) )
2009-12-25 16:50:53 +01:00
def write_struct ( struct ) :
#if not struct.identifier.startswith("Sc") and not struct.identifier.startswith("I"):
# return
2010-01-02 20:01:19 +01:00
#if not struct.identifier == "Object":
# return
2009-12-25 16:50:53 +01:00
filepath = os . path . join ( BASEPATH , " bpy.types. %s .rst " % struct . identifier )
file = open ( filepath , " w " )
fw = file . write
2010-04-10 20:35:50 +02:00
base_id = getattr ( struct . base , " identifier " , " " )
if _BPY_STRUCT_FAKE :
if not base_id :
base_id = _BPY_STRUCT_FAKE
if base_id :
title = " %s ( %s ) " % ( struct . identifier , base_id )
2009-12-25 16:50:53 +01:00
else :
title = struct . identifier
fw ( " %s \n %s \n \n " % ( title , " = " * len ( title ) ) )
fw ( " .. module:: bpy.types \n \n " )
2010-04-10 20:35:50 +02:00
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 :
2009-12-25 16:50:53 +01:00
fw ( " base classes --- " )
else :
fw ( " base class --- " )
2010-09-19 09:07:14 +02:00
fw ( " , " . join ( ( " :class:` %s ` " % base_id ) for base_id in base_ids ) )
2009-12-25 16:50:53 +01:00
fw ( " \n \n " )
2010-04-10 20:35:50 +02:00
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 :
2010-09-19 09:07:14 +02:00
fw ( " subclasses --- \n " + " , " . join ( ( " :class:` %s ` " % s ) for s in subclass_ids ) + " \n \n " )
2009-12-25 16:50:53 +01:00
2010-04-10 20:35:50 +02:00
base_id = getattr ( struct . base , " identifier " , " " )
if _BPY_STRUCT_FAKE :
if not base_id :
base_id = _BPY_STRUCT_FAKE
2009-12-25 16:50:53 +01:00
2010-04-10 20:35:50 +02:00
if base_id :
fw ( " .. class:: %s ( %s ) \n \n " % ( struct . identifier , base_id ) )
2009-12-25 16:50:53 +01:00
else :
fw ( " .. class:: %s \n \n " % struct . identifier )
fw ( " %s \n \n " % struct . description )
2010-06-28 02:06:23 +02:00
# properties sorted in alphabetical order
2010-07-15 13:51:43 +02:00
sorted_struct_properties = struct . properties [ : ]
sorted_struct_properties . sort ( key = lambda prop : prop . identifier )
2010-06-28 02:06:23 +02:00
for prop in sorted_struct_properties :
type_descr = prop . get_type_description ( class_fmt = " :class:` %s ` " )
# readonly properties use "data" directive, variables properties use "attribute" directive
if ' readonly ' in type_descr :
fw ( " .. data:: %s \n \n " % prop . identifier )
else :
fw ( " .. attribute:: %s \n \n " % prop . identifier )
2009-12-26 17:47:25 +01:00
if prop . description :
fw ( " %s \n \n " % prop . description )
2010-06-02 23:28:17 +02:00
fw ( " :type: %s \n \n " % type_descr )
2009-12-25 16:50:53 +01:00
# python attributes
py_properties = struct . get_py_properties ( )
py_prop = None
for identifier , py_prop in py_properties :
2010-01-22 03:04:25 +01:00
pyprop2sphinx ( " " , fw , identifier , py_prop )
2009-12-25 16:50:53 +01:00
del py_properties , py_prop
for func in struct . functions :
2010-09-19 09:07:14 +02:00
args_str = " , " . join ( prop . get_arg_default ( force = False ) for prop in func . args )
2009-12-25 16:50:53 +01:00
2010-08-17 16:32:14 +02:00
fw ( " .. %s :: %s ( %s ) \n \n " % ( " classmethod " if func . is_classmethod else " method " , func . identifier , args_str ) )
2009-12-25 16:50:53 +01:00
fw ( " %s \n \n " % func . description )
for prop in func . args :
2009-12-26 17:47:25 +01:00
write_param ( " " , fw , prop )
2010-01-02 19:55:07 +01:00
if len ( func . return_values ) == 1 :
write_param ( " " , fw , func . return_values [ 0 ] , is_return = True )
2010-01-17 21:59:35 +01:00
elif func . return_values : # multiple return values
2010-09-19 09:07:14 +02:00
fw ( " :return ( %s ): \n " % " , " . join ( prop . identifier for prop in func . return_values ) )
2010-01-02 19:55:07 +01:00
for prop in func . return_values :
2010-01-17 21:59:35 +01:00
type_descr = prop . get_type_description ( as_ret = True , class_fmt = " :class:` %s ` " )
2010-01-02 19:55:07 +01:00
descr = prop . description
if not descr :
descr = prop . name
2010-01-17 21:59:35 +01:00
fw ( " ` %s `, %s , %s \n \n " % ( prop . identifier , descr , type_descr ) )
2010-01-02 19:55:07 +01:00
2009-12-26 17:47:25 +01:00
fw ( " \n " )
2009-12-25 16:50:53 +01:00
# python methods
py_funcs = struct . get_py_functions ( )
py_func = None
for identifier , py_func in py_funcs :
2010-01-22 03:04:25 +01:00
pyfunc2sphinx ( " " , fw , identifier , py_func , is_class = True )
2009-12-25 16:50:53 +01:00
del py_funcs , py_func
2010-04-09 22:43:58 +02:00
lines = [ ]
2010-04-10 20:35:50 +02:00
if struct . base or _BPY_STRUCT_FAKE :
2010-04-09 22:43:58 +02:00
bases = list ( reversed ( struct . get_bases ( ) ) )
2010-04-10 20:35:50 +02:00
2010-04-09 22:43:58 +02:00
# props
lines [ : ] = [ ]
2010-04-10 20:35:50 +02:00
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 :
2010-09-03 11:21:40 +02:00
lines . append ( " * :class:` %s . %s ` \n " % ( _BPY_STRUCT_FAKE , key ) )
2010-04-10 20:35:50 +02:00
2010-04-09 22:43:58 +02:00
for base in bases :
for prop in base . properties :
2010-09-03 11:21:40 +02:00
lines . append ( " * :class:` %s . %s ` \n " % ( base . identifier , prop . identifier ) )
2010-04-09 22:43:58 +02:00
for identifier , py_prop in base . get_py_properties ( ) :
2010-09-03 11:21:40 +02:00
lines . append ( " * :class:` %s . %s ` \n " % ( base . identifier , identifier ) )
2010-04-10 20:35:50 +02:00
for identifier , py_prop in base . get_py_properties ( ) :
2010-09-03 11:21:40 +02:00
lines . append ( " * :class:` %s . %s ` \n " % ( base . identifier , identifier ) )
2010-04-09 22:43:58 +02:00
if lines :
fw ( " .. rubric:: Inherited Properties \n \n " )
2010-09-03 11:21:40 +02:00
fw ( " .. hlist:: \n " )
2010-09-03 16:53:54 +02:00
fw ( " :columns: 2 \n \n " )
2010-09-03 11:21:40 +02:00
2010-04-09 22:43:58 +02:00
for line in lines :
fw ( line )
fw ( " \n " )
# funcs
lines [ : ] = [ ]
2010-04-10 20:35:50 +02:00
if _BPY_STRUCT_FAKE :
for key , descr in descr_items :
if type ( descr ) == MethodDescriptorType :
2010-09-03 11:21:40 +02:00
lines . append ( " * :class:` %s . %s ` \n " % ( _BPY_STRUCT_FAKE , key ) )
2010-04-10 20:35:50 +02:00
2010-04-09 22:43:58 +02:00
for base in bases :
for func in base . functions :
2010-09-03 11:21:40 +02:00
lines . append ( " * :class:` %s . %s ` \n " % ( base . identifier , func . identifier ) )
2010-04-09 22:43:58 +02:00
for identifier , py_func in base . get_py_functions ( ) :
2010-09-03 11:21:40 +02:00
lines . append ( " * :class:` %s . %s ` \n " % ( base . identifier , identifier ) )
2010-04-09 22:43:58 +02:00
if lines :
fw ( " .. rubric:: Inherited Functions \n \n " )
2010-09-03 11:21:40 +02:00
fw ( " .. hlist:: \n " )
2010-09-03 16:53:54 +02:00
fw ( " :columns: 2 \n \n " )
2010-09-03 11:21:40 +02:00
2010-04-09 22:43:58 +02:00
for line in lines :
fw ( line )
fw ( " \n " )
lines [ : ] = [ ]
2009-12-25 16:50:53 +01:00
if struct . references :
# use this otherwise it gets in the index for a normal heading.
fw ( " .. rubric:: References \n \n " )
2010-09-03 11:21:40 +02:00
fw ( " .. hlist:: \n " )
2010-09-03 16:53:54 +02:00
fw ( " :columns: 2 \n \n " )
2010-09-03 11:21:40 +02:00
2009-12-25 16:50:53 +01:00
for ref in struct . references :
ref_split = ref . split ( " . " )
if len ( ref_split ) > 2 :
ref = ref_split [ - 2 ] + " . " + ref_split [ - 1 ]
2010-09-03 11:21:40 +02:00
fw ( " * :class:` %s ` \n " % ref )
2009-12-25 16:50:53 +01:00
fw ( " \n " )
for struct in structs . values ( ) :
2010-02-16 16:01:34 +01:00
# TODO, rna_info should filter these out!
if " _OT_ " in struct . identifier :
continue
2009-12-25 16:50:53 +01:00
write_struct ( struct )
2010-04-10 20:35:50 +02:00
# special case, bpy_struct
if _BPY_STRUCT_FAKE :
filepath = os . path . join ( BASEPATH , " bpy.types. %s .rst " % _BPY_STRUCT_FAKE )
file = open ( filepath , " w " )
fw = file . write
fw ( " %s \n " % _BPY_STRUCT_FAKE )
fw ( " = " * len ( _BPY_STRUCT_FAKE ) + " \n " )
fw ( " \n " )
fw ( " .. module:: bpy.types \n " )
fw ( " \n " )
subclass_ids = [ s . identifier for s in structs . values ( ) if s . base is None if not rna_info . rna_id_ignore ( s . identifier ) ]
if subclass_ids :
2010-09-19 09:07:14 +02:00
fw ( " subclasses --- \n " + " , " . join ( ( " :class:` %s ` " % s ) for s in sorted ( subclass_ids ) ) + " \n \n " )
2010-04-10 20:35:50 +02:00
2010-06-12 00:41:13 +02:00
fw ( " .. class:: %s \n \n " % _BPY_STRUCT_FAKE )
fw ( " built-in base class for all classes in bpy.types. \n \n " )
fw ( " .. note:: \n \n " )
fw ( " Note that bpy.types. %s is not actually available from within blender, it only exists for the purpose of documentation. \n \n " % _BPY_STRUCT_FAKE )
2010-04-10 20:35:50 +02:00
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
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 )
2009-12-25 16:50:53 +01:00
2010-06-04 15:47:56 +02:00
# operators
2009-12-25 16:50:53 +01:00
def write_ops ( ) :
2010-06-04 15:47:56 +02:00
API_BASEURL = ' https://svn.blender.org/svnroot/bf-blender/trunk/blender/release/scripts '
2009-12-25 16:50:53 +01:00
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 : ] )
fw ( " %s \n %s \n \n " % ( title , " = " * len ( title ) ) )
fw ( " .. module:: bpy.ops. %s \n \n " % op . module_name )
last_mod = op . module_name
2010-04-10 20:35:50 +02:00
2010-09-19 09:07:14 +02:00
args_str = " , " . join ( prop . get_arg_default ( force = True ) for prop in op . args )
2009-12-25 16:50:53 +01:00
fw ( " .. function:: %s ( %s ) \n \n " % ( op . func_name , args_str ) )
2010-06-12 00:41:13 +02:00
# 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) " :
2010-06-15 04:06:01 +02:00
operator_description = undocumented_message ( ' bpy.ops ' , op . module_name , op . func_name )
2010-06-12 00:41:13 +02:00
else :
operator_description = op . description
fw ( " %s \n \n " % operator_description )
2009-12-25 16:50:53 +01:00
for prop in op . args :
2010-01-17 21:59:35 +01:00
write_param ( " " , fw , prop )
2009-12-26 17:47:25 +01:00
if op . args :
fw ( " \n " )
2009-12-25 16:50:53 +01:00
location = op . get_location ( )
if location != ( None , None ) :
2010-06-04 15:47:56 +02:00
fw ( " :file: ` %s < %s / %s >`_: %d \n \n " % ( location [ 0 ] , API_BASEURL , location [ 0 ] , location [ 1 ] ) )
2009-12-25 16:50:53 +01:00
write_ops ( )
file . close ( )
2010-07-19 15:36:10 +02:00
def main ( ) :
import bpy
2009-12-25 16:50:53 +01:00
if ' bpy ' not in dir ( ) :
print ( " \n Error, this script must run from inside blender2.5 " )
print ( script_help_msg )
else :
2010-01-31 22:52:26 +01:00
import shutil
2010-10-13 12:42:33 +02:00
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 ' )
2010-05-03 17:52:15 +02:00
# only for partial updates
path_in_tmp = path_in + " -tmp "
2010-01-31 22:52:26 +01:00
2010-05-09 19:18:57 +02:00
if not os . path . exists ( path_in ) :
os . mkdir ( path_in )
2010-02-28 14:45:08 +01:00
for f in os . listdir ( path_examples ) :
if f . endswith ( " .py " ) :
EXAMPLE_SET . add ( os . path . splitext ( f ) [ 0 ] )
2010-01-31 22:52:26 +01:00
2010-05-03 17:52:15 +02:00
# only for full updates
if _BPY_FULL_REBUILD :
shutil . rmtree ( path_in , True )
shutil . rmtree ( path_out , True )
else :
# write here, then move
shutil . rmtree ( path_in_tmp , True )
rna2sphinx ( path_in_tmp )
if not _BPY_FULL_REBUILD :
import filecmp
# 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 :
print ( " \t deprecated: %s " % f )
os . remove ( os . path . join ( path_in , f ) )
# freshen with new files.
for f in sorted ( file_list_path_in_tmp ) :
f_from = os . path . join ( path_in_tmp , f )
f_to = os . path . join ( path_in , f )
do_copy = True
if f in file_list_path_in :
if filecmp . cmp ( f_from , f_to ) :
do_copy = False
if do_copy :
print ( " \t updating: %s " % f )
shutil . copy ( f_from , f_to )
''' else:
print ( " \t keeping: %s " % f ) # eh, not that useful'''
2010-02-28 14:45:08 +01:00
EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED
if EXAMPLE_SET_UNUSED :
print ( " \n Unused examples found in ' %s ' ... " % path_examples )
for f in EXAMPLE_SET_UNUSED :
print ( " %s .py " % f )
print ( " %d total \n " % len ( EXAMPLE_SET_UNUSED ) )
2009-12-25 16:50:53 +01:00
import sys
sys . exit ( )
2010-07-19 15:36:10 +02:00
if __name__ == ' __main__ ' :
main ( )