[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [11145] branches/pyapi_devel/source/ blender/python/api2_2x: Testing a way to have python docs in Blenders PyAPI docstrings.
Campbell Barton
cbarton at metavr.com
Mon Jul 2 14:22:30 CEST 2007
Revision: 11145
http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=11145
Author: campbellbarton
Date: 2007-07-02 14:22:30 +0200 (Mon, 02 Jul 2007)
Log Message:
-----------
Testing a way to have python docs in Blenders PyAPI docstrings.
rather then maintaining 2 sets of docs which is what we have done for a long time.
Works for Group and Camera now, here are the results
http://members.optusnet.com.au/cjbarton/bpy_docs/camera.Camera-class.html
http://members.optusnet.com.au/cjbarton/bpy_docs/group.Group-class.html
This means the C docstrings need to contain epydoc formatting (humanly readable) but need to be changed in the C files. though editing be done in py files and the final version copied back into the .c file.
_epy_write_docstrings.py - extracts epydocs and examples into their own py files.
_epy_docgen.sh - runs _epy_write_docstrings.py in background mode and then epydoc to make the html docs.
advantage is less work with duplicate docs, we can automate running all examples within the docs to make sure they work.
Modified Paths:
--------------
branches/pyapi_devel/source/blender/python/api2_2x/Camera.c
branches/pyapi_devel/source/blender/python/api2_2x/Group.c
branches/pyapi_devel/source/blender/python/api2_2x/Mesh.c
branches/pyapi_devel/source/blender/python/api2_2x/Sound.c
branches/pyapi_devel/source/blender/python/api2_2x/bpy_list.c
branches/pyapi_devel/source/blender/python/api2_2x/gen_library.h
branches/pyapi_devel/source/blender/python/api2_2x/matrix.c
Added Paths:
-----------
branches/pyapi_devel/source/blender/python/api2_2x/doc/_epy_docgen.sh
branches/pyapi_devel/source/blender/python/api2_2x/doc/_epy_write_docstrings.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/examples/
Removed Paths:
-------------
branches/pyapi_devel/source/blender/python/api2_2x/doc/API_intro.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/API_related.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Armature.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/BGL.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/BezTriple.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Blender.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Blender_API.css
branches/pyapi_devel/source/blender/python/api2_2x/doc/Bpy.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Bpy_config.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Bpy_data.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Camera.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Constraint.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Curve.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Curvedoc.txt
branches/pyapi_devel/source/blender/python/api2_2x/doc/Draw.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Effect.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Effectdoc.txt
branches/pyapi_devel/source/blender/python/api2_2x/doc/Font.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Geometry.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Group.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/IDProp.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Image.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Ipo.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/IpoCurve.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Ipodoc.txt
branches/pyapi_devel/source/blender/python/api2_2x/doc/Key.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Lamp.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Lattice.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/LibData.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Library.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Material.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Mathutils.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Mesh.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/MeshPrimitives.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Metaball.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Metaballdoc.txt
branches/pyapi_devel/source/blender/python/api2_2x/doc/Modifier.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/NLA.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/NMesh.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Noise.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Object.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Pose.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Radio.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Registry.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Render.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Scene.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Sound.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Sys.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Text.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Text3d.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Texture.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Theme.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/TimeLine.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Types.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Window.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/World.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/Worlddoc.txt
branches/pyapi_devel/source/blender/python/api2_2x/doc/epy_docgen.sh
branches/pyapi_devel/source/blender/python/api2_2x/doc/id_generics.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/pupblock.blend
branches/pyapi_devel/source/blender/python/api2_2x/doc/testbgl.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/testcamera.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/testcurve.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/testeffect.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/testipo.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/testmball.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/testtext.py
branches/pyapi_devel/source/blender/python/api2_2x/doc/testworld.py
Modified: branches/pyapi_devel/source/blender/python/api2_2x/Camera.c
===================================================================
--- branches/pyapi_devel/source/blender/python/api2_2x/Camera.c 2007-07-02 12:04:22 UTC (rev 11144)
+++ branches/pyapi_devel/source/blender/python/api2_2x/Camera.c 2007-07-02 12:22:30 UTC (rev 11145)
@@ -65,7 +65,44 @@
EXPP_CAM_ATTR_ALPHA,
};
+static char Camera_Type_doc[] ="\
+class Camera:\n\
+ '''\n\
+ The Camera Data object\n\
+ ======================\n\
+ This object gives access to Camera-specific data in Blender.\n\
+ \n\
+ Example::\n\
+ \n\
+ import bpy\n\
+ cam = bpy.data.cameras.new() # create new ortho camera data\n\
+ cam.orthographic = True # create new ortho camera data\n\
+ cam.scale = 6.0 # set scale value for ortho view\n\
+ sce = bpy.data.scenes.active # get current scene\n\
+ ob = scn.objects.new(cam) # add a new camera object from the data\n\
+ scn.camera = ob # make this camera the active\n\
+";
+static char Camera_copy_doc[] ="\
+():\n\
+ '''\n\
+ Make a copy of this camera\n\
+ @rtype: Camera\n\
+ @return: a copy of this camera\n\
+ '''\n\
+";
+
+static char Camera_insertkey_doc[] ="\
+(ipo):\n\
+ '''\n\
+ Inserts a key into IPO\n\
+ @type ipo: Blender Constant\n\
+ @param ipo: Constant for the IPO key, not yet implimented.\n\
+ '''\n\
+";
+
+
+
/*****************************************************************************/
/* Python BPy_Camera methods: */
/*****************************************************************************/
@@ -134,11 +171,11 @@
static PyMethodDef BPy_Camera_methods[] = {
/* name, method, flags, doc */
{"insertKey", ( PyCFunction ) Camera_insertKey, METH_VARARGS,
- "( Camera IPO type ) - Inserts a key into IPO"},
+ Camera_insertkey_doc},
{"__copy__", ( PyCFunction ) Camera_copy, METH_NOARGS,
- "() - Return a copy of the camera."},
+ Camera_copy_doc},
{"copy", ( PyCFunction ) Camera_copy, METH_NOARGS,
- "() - Return a copy of the camera."},
+ Camera_copy_doc},
{NULL, NULL, 0, NULL}
};
@@ -357,7 +394,6 @@
return 0;
}
-
/*****************************************************************************/
/* Python attributes get/set structure: */
/*****************************************************************************/
@@ -365,82 +401,104 @@
GENERIC_LIB_GETSETATTR,
GENERIC_LIB_GETSETATTR_SCRIPTLINK,
{"orthographic",
- (getter)Camera_getOrtho, (setter)Camera_setOrtho,
- "camera orthographic mode",
+ (getter)Camera_getOrtho, (setter)Camera_setOrtho, "\
+ at ivar orthographic: When true this camera will render with no perspective.\n\
+ at type orthographic: bool",
NULL},
{"ipo",
- (getter)Camera_getIpo, (setter)Camera_setIpo,
- "Cameras ipo",
+ (getter)Camera_getIpo, (setter)Camera_setIpo, "\
+ at ivar ipo: The ipo linked to this camera data object.\n\
+ Assign None to clear the ipo from this camera.\n\
+ at type ipo: Blender Ipo",
NULL},
/* float settings */
{"lens",
- (getter)getFloatAttr, (setter)setFloatAttrClamp,
- "lens angle for perspective cameras",
+ (getter)getFloatAttr, (setter)setFloatAttrClamp, "\
+ at ivar lens: The lens value in [1.0, 250.0], only relevant to cameras with their orthographic is set to False.\n\
+ at type lens: float",
(void *)EXPP_CAM_ATTR_LENS},
{"angle",
- (getter)getFloatAttr, (setter)setFloatAttrClamp,
- "lens angle for perspective cameras",
+ (getter)getFloatAttr, (setter)setFloatAttrClamp, "\
+ at ivar angle: The lens value in degrees [7.323871, 172.847331], only relevant to cameras with their orthographic is set to False.\n\
+ at type angle: float",
(void *)EXPP_CAM_ATTR_ANGLE},
{"scale",
- (getter)getFloatAttr, (setter)setFloatAttrClamp,
- "scale for ortho cameras",
+ (getter)getFloatAttr, (setter)setFloatAttrClamp, "\
+ at ivar scale: The scale value in [0.01, 1000.00], only relevant to cameras with their orthographic is set to True.\n\
+ at type scale: float",
(void *)EXPP_CAM_ATTR_SCALE},
{"clipStart",
- (getter)getFloatAttr, (setter)setFloatAttrClamp,
- "the cameras clip start",
+ (getter)getFloatAttr, (setter)setFloatAttrClamp, "\
+ at ivar clipStart: The clip start value in [0.0, 100.0].\n\
+ at type clipStart: float",
(void *)EXPP_CAM_ATTR_CLIPSTART},
{"clipEnd",
- (getter)getFloatAttr, (setter)setFloatAttrClamp,
- "the cameras clip end",
+ (getter)getFloatAttr, (setter)setFloatAttrClamp, "\
+ at ivar clipEnd: The clip end value in [1.0, 5000.0].\n\
+ at type clipEnd: float",
(void *)EXPP_CAM_ATTR_CLIPEND},
{"shiftX",
- (getter)getFloatAttr, (setter)setFloatAttrClamp,
- "the cameras X perspective shift",
+ (getter)getFloatAttr, (setter)setFloatAttrClamp, "\
+ at ivar shiftX: The horizontal offset of the camera [-2.0, 2.0].\n\
+ at type shiftX: float",
(void *)EXPP_CAM_ATTR_SHIFTX},
{"shiftY",
- (getter)getFloatAttr, (setter)setFloatAttrClamp,
- "the cameras Y perspective shift",
+ (getter)getFloatAttr, (setter)setFloatAttrClamp, "\
+ at ivar shiftY: The vertical offset of the camera [-2.0, 2.0].\n\
+ at type shiftY: float",
(void *)EXPP_CAM_ATTR_SHIFTY},
{"dofDist",
- (getter)getFloatAttr, (setter)setFloatAttrClamp,
- "cameras dof distance",
+ (getter)getFloatAttr, (setter)setFloatAttrClamp, "\
+ at ivar dofDist: The focal point of the camera in [0.0, 5000.0].\n\
+ at type dofDist: float",
(void *)EXPP_CAM_ATTR_DOFDIST},
{"drawSize",
- (getter)getFloatAttr, (setter)setFloatAttrClamp,
- "the cameras display size",
+ (getter)getFloatAttr, (setter)setFloatAttrClamp, "\
+ at ivar drawSize: The display size for the camera an the 3d view [0.1, 10.0].\n\
+ at type drawSize: float",
(void *)EXPP_CAM_ATTR_DRAWSIZE},
{"alpha",
- (getter)getFloatAttr, (setter)setFloatAttrClamp,
- "passepart alpha value for display",
+ (getter)getFloatAttr, (setter)setFloatAttrClamp, "\
+ at ivar alpha: The PassePart alpha [0.0, 1.0].\n\
+ at type alpha: float",
(void *)EXPP_CAM_ATTR_ALPHA},
/* flags - use flags as defined in DNA_camera_types.h */
{"drawLimits",
- (getter)getFlagAttr, (setter)setFlagAttr,
- "toggle the draw limits display flag",
+ (getter)getFlagAttr, (setter)setFlagAttr, "\
+ at ivar drawLimits: Display drawlimits in the 3D view for this camera.\n\
+ at type drawLimits: bool",
(void *)CAM_SHOWLIMITS},
{"drawMist",
- (getter)getFlagAttr, (setter)setFlagAttr,
- "toggle the draw mist display flag",
+ (getter)getFlagAttr, (setter)setFlagAttr, "\
+ at ivar drawMist: Display mist limits in the 3D view for this camera.\n\
+ at type drawMist: bool",
(void *)CAM_SHOWMIST},
{"drawName",
- (getter)getFlagAttr, (setter)setFlagAttr,
- "toggle the draw name display flag",
+ (getter)getFlagAttr, (setter)setFlagAttr, "\
+ at ivar drawName: Display camera name in the 3D view.\n\
+ at type drawName: bool",
(void *)CAM_SHOWNAME},
- {"drawTileSafe",
- (getter)getFlagAttr, (setter)setFlagAttr,
- "toggle the tile safe display flag",
+ {"drawTitleSafe",
+ (getter)getFlagAttr, (setter)setFlagAttr, "\
+ at ivar drawTitleSafe: Display title safe bounds in the 3D view for this camera.\n\
+ at type drawTitleSafe: bool",
(void *)CAM_SHOWTITLESAFE},
{"drawPassepartout",
- (getter)getFlagAttr, (setter)setFlagAttr,
- "toggle the passPartOut display flag",
+ (getter)getFlagAttr, (setter)setFlagAttr, "\
+ at ivar drawPassepartout: Mask areas outside the camera view.\n\
+ at type drawPassepartout: bool",
(void *)CAM_SHOWPASSEPARTOUT},
+/* Why would python need to modify this flag? */
+#if 0
{"angleToggle",
- (getter)getFlagAttr, (setter)setFlagAttr,
- "toggle the camera input unit flag",
+ (getter)getFlagAttr, (setter)setFlagAttr, "\
+ at ivar angleToggle: Display the \n\
+ at type angleToggle: bool",
(void *)CAM_ANGLETOGGLE},
+#endif
{NULL,NULL,NULL,NULL} /* Sentinel */
};
@@ -485,7 +543,7 @@
/*** Flags to define presence of optional/expanded features ***/
Py_TPFLAGS_DEFAULT, /* long tp_flags; */
- NULL, /* char *tp_doc; Documentation string */
+ Camera_Type_doc, /* char *tp_doc; Documentation string */
/*** Assigned meaning in release 2.0 ***/
/* call function for all accessible objects */
NULL, /* traverseproc tp_traverse; */
Modified: branches/pyapi_devel/source/blender/python/api2_2x/Group.c
===================================================================
--- branches/pyapi_devel/source/blender/python/api2_2x/Group.c 2007-07-02 12:04:22 UTC (rev 11144)
+++ branches/pyapi_devel/source/blender/python/api2_2x/Group.c 2007-07-02 12:22:30 UTC (rev 11145)
@@ -53,6 +53,112 @@
#define GROUP_DEL_CHECK_PY(bpy_group) if (!(bpy_group->group)) return ( EXPP_ReturnPyObjError( PyExc_RuntimeError, "Group has been removed" ) )
#define GROUP_DEL_CHECK_INT(bpy_group) if (!(bpy_group->group)) return ( EXPP_ReturnIntError( PyExc_RuntimeError, "Group has been removed" ) )
+static char Group_Type_doc[] ="\
+class Group:\n\
+ '''\n\
+ The Group object\n\
+ ================\n\
+ This object gives access to Groups in Blender.\n\
+ \n\
+ Example::\n\
+ \n\
+ # Make Dupli's Real, as a python script.\n\
+ \n\
+ from Blender import *\n\
+ import bpy\n\
+ \n\
+ sce= bpy.data.scenes.active\n\
+ for ob in sce.objects:\n\
+ print 'Object Group Settings'\n\
+ print ob.name, ob.type\n\
+ print 'enableDupVerts:', ob.enableDupVerts\n\
+ print 'enableDupFrames:', ob.enableDupFrames\n\
+ print 'enableDupGroup:', ob.enableDupGroup\n\
+ print 'DupGroup:', ob.DupGroup\n\
+ dupe_obs= ob.DupObjects\n\
+ print 'num dup obs:', len(dupe_obs)\n\
+ \n\
+ for dup_ob, dup_matrix in dupe_obs:\n\
+ print '\tDupOb', dup_ob.name\n\
+ scn.objects.new(dup_ob.data)\n\
+ new_ob.setMatrix(dup_matrix)\n\
+ new_ob.sel= 1 # select all real instances.\n\
+ \n\
+ ob.sel=0 # Desel the original object\n\
+ \n\
+ Window.RedrawAll()\n\
+ \n\
+ Example::\n\
+ \n\
+ # Make a new group with the selected objects, and add an instance of this group.\n\
+ \n\
+ from Blender import *\n\
+ import bpy\n\
+ \n\
+ sce= bpy.data.scenes.active\n\
+ \n\
+ # New Group\n\
+ grp= bpy.data.groups.new('mygroup')\n\
+ grp.objects= list(scn.objects)\n\
+ \n\
+ # Instance the group at an empty using dupligroups\n\
+ ob= sce.objects.new(None)\n\
+ ob.enableDupGroup= True\n\
+ ob.DupGroup= grp\n\
+ Window.RedrawAll()\n\
+ \n\
+ Example::\n\
+ \n\
+ # Remove all non mesh objects from a group.\n\
+ \n\
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list