From baa8b63111f2ac5439155b6e0807a22f550b40f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= Date: Sun, 1 Feb 2015 16:06:32 +0100 Subject: [PATCH] Documentation: updated mathutils documentation Added descriptions of the constructors, and improved the module-level documentation. --- source/blender/python/mathutils/mathutils.c | 13 +++++++++- .../python/mathutils/mathutils_Color.c | 7 ++++- .../python/mathutils/mathutils_Euler.c | 9 ++++++- .../python/mathutils/mathutils_Matrix.c | 9 ++++++- .../python/mathutils/mathutils_Quaternion.c | 26 ++++++++++++++++++- .../python/mathutils/mathutils_Vector.c | 7 ++++- 6 files changed, 65 insertions(+), 6 deletions(-) diff --git a/source/blender/python/mathutils/mathutils.c b/source/blender/python/mathutils/mathutils.c index ecaaae80aa2..ca20f837b4a 100644 --- a/source/blender/python/mathutils/mathutils.c +++ b/source/blender/python/mathutils/mathutils.c @@ -38,7 +38,18 @@ #endif PyDoc_STRVAR(M_Mathutils_doc, -"This module provides access to matrices, eulers, quaternions and vectors." +"This module provides access to the math classes:\n" +"\n" +"- :class:`Color`,\n" +"- :class:`Euler`,\n" +"- :class:`Matrix`,\n" +"- :class:`Quaternion`,\n" +"- :class:`Vector`,\n" +"\n" +".. note::\n" +"\n" +" Classes, methods and attributes that accept vectors also accept other numeric sequences,\n" +" such as tuples, lists." ); static int mathutils_array_parse_fast(float *array, int size, diff --git a/source/blender/python/mathutils/mathutils_Color.c b/source/blender/python/mathutils/mathutils_Color.c index 8426038f2d4..ce590999bc1 100644 --- a/source/blender/python/mathutils/mathutils_Color.c +++ b/source/blender/python/mathutils/mathutils_Color.c @@ -811,7 +811,12 @@ static struct PyMethodDef Color_methods[] = { /* ------------------PY_OBECT DEFINITION-------------------------- */ PyDoc_STRVAR(color_doc, -"This object gives access to Colors in Blender." +".. class:: Color(rgb)\n" +"\n" +" This object gives access to Colors in Blender.\n" +"\n" +" :param rgb: (r, g, b) color values\n" +" :type rgb: 3d vector\n" ); PyTypeObject color_Type = { PyVarObject_HEAD_INIT(NULL, 0) diff --git a/source/blender/python/mathutils/mathutils_Euler.c b/source/blender/python/mathutils/mathutils_Euler.c index 9c0ced39403..edb4af0aa1d 100644 --- a/source/blender/python/mathutils/mathutils_Euler.c +++ b/source/blender/python/mathutils/mathutils_Euler.c @@ -657,7 +657,14 @@ static struct PyMethodDef Euler_methods[] = { /* ------------------PY_OBECT DEFINITION-------------------------- */ PyDoc_STRVAR(euler_doc, -"This object gives access to Eulers in Blender." +".. class:: Euler(angles, order='XYZ')\n" +"\n" +" This object gives access to Eulers in Blender.\n" +"\n" +" :param angles: Three angles, in radians.\n" +" :type angles: 3d vector\n" +" :param order: Optional order of the angles, a permutation of ``XYZ``.\n" +" :type order: str\n" ); PyTypeObject euler_Type = { PyVarObject_HEAD_INIT(NULL, 0) diff --git a/source/blender/python/mathutils/mathutils_Matrix.c b/source/blender/python/mathutils/mathutils_Matrix.c index 4706c09176e..95b53256eac 100644 --- a/source/blender/python/mathutils/mathutils_Matrix.c +++ b/source/blender/python/mathutils/mathutils_Matrix.c @@ -2716,7 +2716,14 @@ static struct PyMethodDef Matrix_methods[] = { /*------------------PY_OBECT DEFINITION--------------------------*/ PyDoc_STRVAR(matrix_doc, -"This object gives access to Matrices in Blender." +".. class:: Matrix([rows])\n" +"\n" +" This object gives access to Matrices in Blender, supporting square and rectangular\n" +" matrices from 2x2 up to 4x4.\n" +"\n" +" :param rows: Sequence of rows.\n" +" When ommitted, a 4x4 identity matrix is constructed.\n" +" :type rows: 2d number sequence\n" ); PyTypeObject matrix_Type = { PyVarObject_HEAD_INIT(NULL, 0) diff --git a/source/blender/python/mathutils/mathutils_Quaternion.c b/source/blender/python/mathutils/mathutils_Quaternion.c index 786a9324adf..42be316bc9b 100644 --- a/source/blender/python/mathutils/mathutils_Quaternion.c +++ b/source/blender/python/mathutils/mathutils_Quaternion.c @@ -187,6 +187,8 @@ PyDoc_STRVAR(Quaternion_to_exponential_map_doc, "\n" " :return: exponential map.\n" " :rtype: :class:`Vector` of size 3\n" +"\n" +" To convert back to a quaternion, pass it to the :class:`Quaternion` constructor.\n" ); static PyObject *Quaternion_to_exponential_map(QuaternionObject *self) { @@ -1226,7 +1228,29 @@ static PyGetSetDef Quaternion_getseters[] = { /* ------------------PY_OBECT DEFINITION-------------------------- */ PyDoc_STRVAR(quaternion_doc, -"This object gives access to Quaternions in Blender." +".. class:: Quaternion([seq, [angle]])\n" +"\n" +" This object gives access to Quaternions in Blender.\n" +"\n" +" :param seq: size 3 or 4\n" +" :type seq: :class:`Vector`\n" +" :param angle: rotation angle, in radians\n" +" :type angle: float\n" +"\n" +" The constructor takes arguments in various forms:\n" +"\n" +" (), *no args*\n" +" Create an identity quaternion\n" +" (*wxyz*)\n" +" Create a quaternion from a ``(w, x, y, z)`` vector.\n" +" (*exponential_map*)\n" +" Create a quaternion from a 3d exponential map vector.\n" +"\n" +" .. seealso:: :meth:`to_exponential_map`\n" +" (*axis, angle*)\n" +" Create a quaternion representing a rotation of *angle* radians over *axis*.\n" +"\n" +" .. seealso:: :meth:`to_axis_angle`\n" ); PyTypeObject quaternion_Type = { PyVarObject_HEAD_INIT(NULL, 0) diff --git a/source/blender/python/mathutils/mathutils_Vector.c b/source/blender/python/mathutils/mathutils_Vector.c index 167fb5bcf3d..091412b0f53 100644 --- a/source/blender/python/mathutils/mathutils_Vector.c +++ b/source/blender/python/mathutils/mathutils_Vector.c @@ -2904,7 +2904,12 @@ static struct PyMethodDef Vector_methods[] = { */ PyDoc_STRVAR(vector_doc, -"This object gives access to Vectors in Blender." +".. class:: Vector(seq)\n" +"\n" +" This object gives access to Vectors in Blender.\n" +"\n" +" :param seq: Components of the vector, must be a sequence of at least two\n" +" :type seq: sequence of numbers\n" ); PyTypeObject vector_Type = { PyVarObject_HEAD_INIT(NULL, 0)