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 = '''
Usage ,
run this script from blenders root path once you have compiled blender
2010-01-31 22:52:26 +01:00
. / blender . bin - b - P / b / source / blender / python / doc / sphinx_doc_gen . py
2009-12-25 16:50:53 +01:00
2010-01-06 10:42:41 +01:00
This will generate python files in " ./source/blender/python/doc/sphinx-in "
2009-12-25 16:50:53 +01:00
Generate html docs by running . . .
2010-01-06 10:42:41 +01:00
sphinx - build source / blender / python / doc / sphinx - in source / blender / python / doc / sphinx - out
2010-01-28 11:48:17 +01:00
For PDF generation
sphinx - build - b latex source / blender / python / doc / sphinx - in source / blender / python / doc / sphinx - out
cd source / blender / python / doc / sphinx - out
make
2009-12-25 16:50:53 +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
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
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 "
2009-12-25 16:50:53 +01:00
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 )
2010-02-28 14:45:08 +01:00
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 ( " \t skipping example: " , example_id )
2010-01-31 22:52:26 +01:00
def write_indented_lines ( ident , fn , text , strip = True ) :
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 ) :
doc = descr . __doc__
if not doc :
doc = " Undocumented "
if type ( descr ) == GetSetDescriptorType :
fw ( ident + " .. attribute:: %s \n \n " % identifier )
write_indented_lines ( ident , fw , doc , False )
elif type ( descr ) == MethodDescriptorType : # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
write_indented_lines ( ident , fw , doc , False )
else :
raise TypeError ( " type was not GetSetDescriptorType or MethodDescriptorType " )
write_example_ref ( ident , fw , module_name + " . " + type_name + " . " + identifier )
fw ( " \n " )
2010-01-22 03:04:25 +01:00
def py_c_func2sphinx ( ident , fw , identifier , py_func , is_class = True ) :
'''
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 )
fw ( ident + " Undocumented function. \n \n " % identifier )
def pyprop2sphinx ( ident , fw , identifier , py_prop ) :
'''
python property to sphinx
'''
fw ( ident + " .. attribute:: %s \n \n " % identifier )
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
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 )
fw ( " \n " )
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 ( " _ " ) :
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.
py_c_func2sphinx ( " " , fw , 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-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 ( " __ " ) ]
for key , descr in descr_items :
2010-01-27 22:33:39 +01:00
if type ( descr ) == MethodDescriptorType : # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
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
2009-12-25 16:50:53 +01:00
fw ( " project = ' Blender 3D ' \n " )
# 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 )
# 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 " )
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 " )
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 ( " `A PDF version of this document is also available <blender_python_reference_250.pdf>`__ \n " )
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 " )
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 " )
fw ( " * modules: bgl, Mathutils and Geometry \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 " )
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 " )
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-01-22 03:04:25 +01:00
2010-01-27 23:17:27 +01:00
fw ( " Mathutils.rst \n \n " )
2010-03-01 11:34:54 +01:00
fw ( " blf.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
fw ( " Blender Operators (bpy.ops) \n " )
fw ( " =========================== \n \n " )
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
fw ( " Blender Types (bpy.types) \n " )
fw ( " ========================= \n \n " )
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-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
# 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
import Mathutils as module
2010-01-27 23:17:27 +01:00
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-02-28 15:57:26 +01:00
pymodule2sphinx ( BASEPATH , " blf " , module , " Blender Font Drawing (blf) " )
2010-02-28 12:54:48 +01:00
del module
2010-01-27 23:17:27 +01: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-01-18 11:45:54 +01:00
fw ( ident + " : %s %s : %s \n " % ( id_name , identifier , " , " . join ( [ val for val in ( prop . name , prop . description ) if val ] ) ) )
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-04-10 20:35:50 +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 :
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 )
for prop in struct . properties :
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-01-17 21:59:35 +01:00
type_descr = prop . get_type_description ( class_fmt = " :class:` %s ` " )
2009-12-26 17:47:25 +01: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 :
args_str = " , " . join ( [ prop . get_arg_default ( force = False ) for prop in func . args ] )
fw ( " .. method:: %s ( %s ) \n \n " % ( func . identifier , args_str ) )
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
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 :
lines . append ( " * :class:` %s . %s ` \n " % ( _BPY_STRUCT_FAKE , key ) )
2010-04-09 22:43:58 +02:00
for base in bases :
for prop in base . properties :
lines . append ( " * :class:` %s . %s ` \n " % ( base . identifier , prop . identifier ) )
for identifier , py_prop in base . get_py_properties ( ) :
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 ( ) :
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 " )
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 :
lines . append ( " * :class:` %s . %s ` \n " % ( _BPY_STRUCT_FAKE , key ) )
2010-04-09 22:43:58 +02:00
for base in bases :
for func in base . functions :
lines . append ( " * :class:` %s . %s ` \n " % ( base . identifier , func . identifier ) )
for identifier , py_func in base . get_py_functions ( ) :
lines . append ( " * :class:` %s . %s ` \n " % ( base . identifier , identifier ) )
if lines :
fw ( " .. rubric:: Inherited Functions \n \n " )
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 " )
for ref in struct . references :
ref_split = ref . split ( " . " )
if len ( ref_split ) > 2 :
ref = ref_split [ - 2 ] + " . " + ref_split [ - 1 ]
fw ( " * :class:` %s ` \n " % ref )
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 :
fw ( " subclasses --- \n " + " , " . join ( [ ( " :class:` %s ` " % s ) for s in sorted ( subclass_ids ) ] ) + " \n \n " )
fw ( " .. class:: %s \n " % _BPY_STRUCT_FAKE )
fw ( " \n " )
fw ( " built-in base class for all classes in bpy.types, note that bpy.types. %s is not actually available from within blender, it only exists for the purpose of documentation. \n " % _BPY_STRUCT_FAKE )
fw ( " \n " )
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
# oeprators
def write_ops ( ) :
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
2009-12-25 16:50:53 +01:00
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 ) )
2009-12-26 17:47:25 +01:00
if op . description :
fw ( " %s \n \n " % op . 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 ) :
fw ( " *python operator source --- ` %s : %d `* \n \n " % location )
write_ops ( )
file . close ( )
if __name__ == ' __main__ ' :
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
path_in = ' source/blender/python/doc/sphinx-in '
path_out = ' source/blender/python/doc/sphinx-in '
2010-02-28 14:45:08 +01:00
path_examples = ' source/blender/python/doc/examples '
2010-01-31 22:52:26 +01:00
shutil . rmtree ( path_in , True )
shutil . rmtree ( path_out , True )
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
rna2sphinx ( path_in )
# for fast module testing
2010-01-27 23:17:27 +01:00
# os.system("rm source/blender/python/doc/sphinx-in/bpy.types.*.rst")
2010-01-31 22:52:26 +01:00
# os.system("rm source/blender/python/doc/sphinx-in/bpy.ops.*.rst")
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 ( )