From b4081bfc7beecf45d58137885c6abac81e3fb27b Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Fri, 10 Dec 2010 00:20:32 +0000 Subject: [PATCH] patch [#25027] formatting mathutils.geometry module docs for sphinx from Luka Bonavita See: http://www.blender.org/documentation/250PythonDoc/mathutils.geometry.html --- doc/python_api/sphinx_doc_gen.py | 25 ++- release/scripts/op/console_python.py | 3 +- source/blender/makesrna/intern/rna_screen.c | 2 +- source/blender/python/generic/blf_py_api.c | 2 +- .../python/generic/mathutils_geometry.c | 156 ++++++++++++++++-- 5 files changed, 170 insertions(+), 18 deletions(-) diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index 1353dcf70d7..ae0bb43d1bc 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -64,11 +64,16 @@ EXAMPLE_SET_USED = set() _BPY_STRUCT_FAKE = "bpy_struct" _BPY_FULL_REBUILD = False + def undocumented_message(module_name, type_name, identifier): - message = "Undocumented (`contribute " \ - "`_)\n\n" % (module_name, type_name, identifier) + if str(type_name).startswith('`_)\n\n" % preloadtitle return message @@ -405,6 +410,9 @@ def rna2sphinx(BASEPATH): fw(" mathutils.rst\n\n") + fw(" mathutils.geometry.rst\n\n") + # XXX TODO + #fw(" bgl.rst\n\n") fw(" blf.rst\n\n") fw(" aud.rst\n\n") @@ -485,11 +493,20 @@ def rna2sphinx(BASEPATH): import mathutils as module pymodule2sphinx(BASEPATH, "mathutils", module, "Math Types & Utilities (mathutils)") del module + + import mathutils.geometry as module + pymodule2sphinx(BASEPATH, "mathutils.geometry", module, "Geometry Utilities (mathutils.geometry)") + del module import blf as module pymodule2sphinx(BASEPATH, "blf", module, "Font Drawing (blf)") del module + # XXX TODO + #import bgl as module + #pymodule2sphinx(BASEPATH, "bgl", module, "Blender OpenGl wrapper (bgl)") + #del module + import aud as module pymodule2sphinx(BASEPATH, "aud", module, "Audio System (aud)") del module diff --git a/release/scripts/op/console_python.py b/release/scripts/op/console_python.py index f5486e6b0bf..b9483cd769a 100644 --- a/release/scripts/op/console_python.py +++ b/release/scripts/op/console_python.py @@ -264,7 +264,8 @@ def banner(context): sc = context.space_data version_string = sys.version.strip().replace('\n', ' ') - add_scrollback(" * Python Interactive Console %s *" % version_string, 'OUTPUT') + add_scrollback("PYTHON INTERACTIVE CONSOLE %s" % version_string, 'OUTPUT') + add_scrollback("", 'OUTPUT') add_scrollback("Command History: Up/Down Arrow", 'OUTPUT') add_scrollback("Cursor: Left/Right Home/End", 'OUTPUT') add_scrollback("Remove: Backspace/Delete", 'OUTPUT') diff --git a/source/blender/makesrna/intern/rna_screen.c b/source/blender/makesrna/intern/rna_screen.c index 197a7266fea..a8c96e93448 100644 --- a/source/blender/makesrna/intern/rna_screen.c +++ b/source/blender/makesrna/intern/rna_screen.c @@ -116,7 +116,7 @@ static void rna_def_area(BlenderRNA *brna) prop= RNA_def_property(srna, "spaces", PROP_COLLECTION, PROP_NONE); RNA_def_property_collection_sdna(prop, NULL, "spacedata", NULL); RNA_def_property_struct_type(prop, "Space"); - RNA_def_property_ui_text(prop, "Spaces", "Spaces contained in this area, the first space is active"); + RNA_def_property_ui_text(prop, "Spaces", "Spaces contained in this area, the first being the active space. NOTE: Useful for example to restore a previously used 3d view space in a certain area to get the old view orientation."); prop= RNA_def_property(srna, "active_space", PROP_POINTER, PROP_NONE); RNA_def_property_pointer_sdna(prop, NULL, "spacedata.first"); diff --git a/source/blender/python/generic/blf_py_api.c b/source/blender/python/generic/blf_py_api.c index bd8512ff2d7..380f2e456bd 100644 --- a/source/blender/python/generic/blf_py_api.c +++ b/source/blender/python/generic/blf_py_api.c @@ -367,7 +367,7 @@ struct PyMethodDef BLF_methods[] = { {"dimensions", (PyCFunction) py_blf_dimensions, METH_VARARGS, py_blf_dimensions_doc}, {"draw", (PyCFunction) py_blf_draw, METH_VARARGS, py_blf_draw_doc}, {"enable", (PyCFunction) py_blf_enable, METH_VARARGS, py_blf_enable_doc}, - {"position", (PyCFunction)py_blf_position, METH_VARARGS, py_blf_position_doc}, + {"position", (PyCFunction) py_blf_position, METH_VARARGS, py_blf_position_doc}, {"rotation", (PyCFunction) py_blf_rotation, METH_VARARGS, py_blf_rotation_doc}, {"shadow", (PyCFunction) py_blf_shadow, METH_VARARGS, py_blf_shadow_doc}, {"shadow_offset", (PyCFunction) py_blf_shadow_offset, METH_VARARGS, py_blf_shadow_offset_doc}, diff --git a/source/blender/python/generic/mathutils_geometry.c b/source/blender/python/generic/mathutils_geometry.c index 4a98a421650..673ce87d9ce 100644 --- a/source/blender/python/generic/mathutils_geometry.c +++ b/source/blender/python/generic/mathutils_geometry.c @@ -45,18 +45,152 @@ /*-------------------------DOC STRINGS ---------------------------*/ static char M_Geometry_doc[] = "The Blender geometry module\n\n"; -static char M_Geometry_Intersect_doc[] = "(v1, v2, v3, ray, orig, clip=1) - returns the intersection between a ray and a triangle, if possible, returns None otherwise"; -static char M_Geometry_TriangleArea_doc[] = "(v1, v2, v3) - returns the area size of the 2D or 3D triangle defined"; -static char M_Geometry_TriangleNormal_doc[] = "(v1, v2, v3) - returns the normal of the 3D triangle defined"; -static char M_Geometry_QuadNormal_doc[] = "(v1, v2, v3, v4) - returns the normal of the 3D quad defined"; -static char M_Geometry_LineIntersect_doc[] = "(v1, v2, v3, v4) - returns a tuple with the points on each line respectively closest to the other"; -static char M_Geometry_PolyFill_doc[] = "(veclist_list) - takes a list of polylines (each point a vector) and returns the point indicies for a polyline filled with triangles"; -static char M_Geometry_LineIntersect2D_doc[] = "(lineA_p1, lineA_p2, lineB_p1, lineB_p2) - takes 2 lines (as 4 vectors) and returns a vector for their point of intersection or None"; -static char M_Geometry_ClosestPointOnLine_doc[] = "(pt, line_p1, line_p2) - takes a point and a line and returns a (Vector, float) for the point on the line, and the bool so you can know if the point was between the 2 points"; -static char M_Geometry_PointInTriangle2D_doc[] = "(pt, tri_p1, tri_p2, tri_p3) - takes 4 vectors, one is the point and the next 3 define the triangle, only the x and y are used from the vectors"; -static char M_Geometry_PointInQuad2D_doc[] = "(pt, quad_p1, quad_p2, quad_p3, quad_p4) - takes 5 vectors, one is the point and the next 4 define the quad, only the x and y are used from the vectors"; +static char M_Geometry_Intersect_doc[] = +".. function:: Intersect(v1, v2, v3, ray, orig, clip=True)\n" +"\n" +" Returns the intersection between a ray and a triangle, if possible, returns None otherwise.\n" +"\n" +" :rtype: boolean\n" +" :arg v1: Point1\n" +" :type v1: :class:`mathutils.Vector`\n" +" :arg v2: Point2\n" +" :type v2: :class:`mathutils.Vector`\n" +" :arg v3: Point3\n" +" :type v3: :class:`mathutils.Vector`\n" +" :arg ray: Direction of the projection\n" +" :type ray: :class:`mathutils.Vector`\n" +" :arg orig: Origin\n" +" :type orig: :class:`mathutils.Vector`\n" +" :arg clip: Clip by the ray length\n" +" :type clip: boolean\n"; + +static char M_Geometry_TriangleArea_doc[] = +".. function:: TriangleArea(v1, v2, v3)\n" +"\n" +" Returns the area size of the 2D or 3D triangle defined.\n" +"\n" +" :rtype: float\n" +" :arg v1: Point1\n" +" :type v1: :class:`mathutils.Vector`\n" +" :arg v2: Point2\n" +" :type v2: :class:`mathutils.Vector`\n" +" :arg v3: Point3\n" +" :type v3: :class:`mathutils.Vector`\n"; + +static char M_Geometry_TriangleNormal_doc[] = +".. function:: TriangleNormal(v1, v2, v3)\n" +"\n" +" Returns the normal of the 3D triangle defined.\n" +"\n" +" :rtype: :class:`mathutils.Vector`\n" +" :arg v1: Point1\n" +" :type v1: :class:`mathutils.Vector`\n" +" :arg v2: Point2\n" +" :type v2: :class:`mathutils.Vector`\n" +" :arg v3: Point3\n" +" :type v3: :class:`mathutils.Vector`\n"; + +static char M_Geometry_QuadNormal_doc[] = +".. function:: QuadNormal(v1, v2, v3, v4)\n" +"\n" +" Returns the normal of the 3D quad defined.\n" +"\n" +" :rtype: :class:`mathutils.Vector`\n" +" :arg v1: Point1\n" +" :type v1: :class:`mathutils.Vector`\n" +" :arg v2: Point2\n" +" :type v2: :class:`mathutils.Vector`\n" +" :arg v3: Point3\n" +" :type v3: :class:`mathutils.Vector`\n" +" :arg v4: Point4\n" +" :type v4: :class:`mathutils.Vector`\n"; + +static char M_Geometry_LineIntersect_doc[] = +".. function:: LineIntersect(v1, v2, v3, v4)\n" +"\n" +" Returns a tuple with the points on each line respectively closest to the other.\n" +"\n" +" :rtype: tuple with elements being of type :class:`mathutils.Vector`\n" +" :arg v1: First point of the first line\n" +" :type v1: :class:`mathutils.Vector`\n" +" :arg v2: Second point of the first line\n" +" :type v2: :class:`mathutils.Vector`\n" +" :arg v3: First point of the second line\n" +" :type v3: :class:`mathutils.Vector`\n" +" :arg v4: Second point of the second line\n" +" :type v4: :class:`mathutils.Vector`\n"; + +static char M_Geometry_PolyFill_doc[] = +".. function:: PolyFill(veclist_list)\n" +"\n" +" Takes a list of polylines (each point a vector) and returns the point indicies for a polyline filled with triangles.\n" +"\n" +" :rtype: list\n" +" :arg veclist_list: list of polylines\n"; + +static char M_Geometry_LineIntersect2D_doc[] = +".. function:: LineIntersect2D(lineA_p1, lineA_p2, lineB_p1, lineB_p2)\n" +"\n" +" Takes 2 lines (as 4 vectors) and returns a vector for their point of intersection or None.\n" +"\n" +" :rtype: :class:`mathutils.Vector`\n" +" :arg lineA_p1: First point of the first line\n" +" :type lineA_p1: :class:`mathutils.Vector`\n" +" :arg lineA_p2: Second point of the first line\n" +" :type lineA_p2: :class:`mathutils.Vector`\n" +" :arg lineB_p1: First point of the second line\n" +" :type lineB_p1: :class:`mathutils.Vector`\n" +" :arg lineB_p2: Second point of the second line\n" +" :type lineB_p2: :class:`mathutils.Vector`\n"; + +static char M_Geometry_ClosestPointOnLine_doc[] = +".. function:: ClosestPointOnLine(pt, line_p1, line_p2)\n" +"\n" +" Takes a point and a line and returns a tuple with the closest point on the line and its distance from the first point of the line as a percentage of the length of the line.\n" +"\n" +" :rtype: (:class:`mathutils.Vector`, float)\n" +" :arg pt: Point\n" +" :type pt: :class:`mathutils.Vector`\n" +" :arg line_p1: First point of the line\n" +" :type line_p1: :class:`mathutils.Vector`\n" +" :arg line_p1: Second point of the line\n" +" :type line_p1: :class:`mathutils.Vector`\n"; + +static char M_Geometry_PointInTriangle2D_doc[] = +".. function:: PointInTriangle2D(pt, tri_p1, tri_p2, tri_p3)\n" +"\n" +" Takes 4 vectors (using only the x and y coordinates): one is the point and the next 3 define the triangle. Returns 1 if the point is within the triangle, otherwise 0.\n" +"\n" +" :rtype: int\n" +" :arg pt: Point\n" +" :type v1: :class:`mathutils.Vector`\n" +" :arg tri_p1: First point of the triangle\n" +" :type tri_p1: :class:`mathutils.Vector`\n" +" :arg tri_p2: Second point of the triangle\n" +" :type tri_p2: :class:`mathutils.Vector`\n" +" :arg tri_p3: Third point of the triangle\n" +" :type tri_p3: :class:`mathutils.Vector`\n"; + +static char M_Geometry_PointInQuad2D_doc[] = +".. function:: PointInQuad2D(pt, quad_p1, quad_p2, quad_p3, quad_p4)\n" +"\n" +" Takes 5 vectors (using only the x and y coordinates): one is the point and the next 4 define the quad, only the x and y are used from the vectors. Returns 1 if the point is within the quad, otherwise 0.\n" +"\n" +" :rtype: int\n" +" :arg pt: Point\n" +" :type v1: :class:`mathutils.Vector`\n" +" :arg quad_p1: First point of the quad\n" +" :type quad_p1: :class:`mathutils.Vector`\n" +" :arg quad_p2: Second point of the quad\n" +" :type quad_p2: :class:`mathutils.Vector`\n" +" :arg quad_p3: Third point of the quad\n" +" :type quad_p3: :class:`mathutils.Vector`\n" +" :arg quad_p4: Forth point of the quad\n" +" :type quad_p4: :class:`mathutils.Vector`\n"; + static char M_Geometry_BoxPack2D_doc[] = ""; static char M_Geometry_BezierInterp_doc[] = ""; +static char M_Geometry_BarycentricTransform_doc[] = ""; //---------------------------------INTERSECTION FUNCTIONS-------------------- //----------------------------------geometry.Intersect() ------------------- @@ -813,7 +947,7 @@ struct PyMethodDef M_Geometry_methods[] = { {"PointInQuad2D", ( PyCFunction ) M_Geometry_PointInQuad2D, METH_VARARGS, M_Geometry_PointInQuad2D_doc}, {"BoxPack2D", ( PyCFunction ) M_Geometry_BoxPack2D, METH_O, M_Geometry_BoxPack2D_doc}, {"BezierInterp", ( PyCFunction ) M_Geometry_BezierInterp, METH_VARARGS, M_Geometry_BezierInterp_doc}, - {"BarycentricTransform", ( PyCFunction ) M_Geometry_BarycentricTransform, METH_VARARGS, NULL}, + {"BarycentricTransform", ( PyCFunction ) M_Geometry_BarycentricTransform, METH_VARARGS, M_Geometry_BarycentricTransform_doc}, {NULL, NULL, 0, NULL} };