bmesh py api: more comprehensive intro page, also fix some spelling errors.

CMakeLists.txt

@@ -124,7 +124,7 @@ mark_as_advanced(WITH_PYTHON)  # dont want people disabling this unless they rea
 mark_as_advanced(WITH_PYTHON_SECURITY)  # some distrobutions see this as a security issue, rather than have them patch it, make a build option.
 
 option(WITH_PYTHON_SAFETY "Enable internal API error checking to track invalid data to prevent crash on access (at the expense of some effeciency, only enable for development)." OFF)
-option(WITH_PYTHON_MODULE "Enable building as a python module (experemental, only enable for development)" OFF)
+option(WITH_PYTHON_MODULE "Enable building as a python module (experimental, only enable for development)" OFF)
 option(WITH_BUILDINFO     "Include extra build details (only disable for development & faster builds)" ON)
 option(WITH_IK_ITASC      "Enable ITASC IK solver (only disable for development & for incompatible C++ compilers)" ON)
 option(WITH_FFTW3         "Enable FFTW3 support (Used for smoke and audio effects)" OFF)
@@ -176,7 +176,7 @@ option(WITH_MOD_SMOKE        	"Enable Smoke Modifier (Smoke Simulation)" ON)
 option(WITH_MOD_DECIMATE       	"Enable Decimate Modifier" ON)
 option(WITH_MOD_BOOLEAN        	"Enable Boolean Modifier" ON)
 option(WITH_MOD_REMESH        	"Enable Remesh Modifier" ON)
-option(WITH_MOD_CLOTH_ELTOPO   	"Enable Experemental cloth solver" OFF)
+option(WITH_MOD_CLOTH_ELTOPO   	"Enable Experimental cloth solver" OFF)
 mark_as_advanced(WITH_MOD_CLOTH_ELTOPO)
 option(WITH_MOD_OCEANSIM        "Enable Ocean Modifier" OFF)
 

doc/python_api/rst/include__bmesh.rst

@@ -0,0 +1,103 @@
+..
+   This document is appended to the auto generated bmesh api doc to avoid clogging up the C files with details.
+   to test this run:
+   ./blender.bin -b -noaudio -P doc/python_api/sphinx_doc_gen.py -- --partial bmesh* ; cd doc/python_api ; sphinx-build sphinx-in sphinx-out ; cd ../../
+
+
+Intro
+-----
+
+This API gives access the blenders internal mesh editing api, featuring geometry connectivity data and
+access to editing operations such as split, separate, collapse and dissolve.
+
+The features exposed closely follow the C API,
+giving python access to the functions used by blenders own mesh editing tools.
+
+For an overview of BMesh data types and how they reference each other see:
+`BMesh Design Document <http://wiki.blender.org/index.php/Dev:2.6/Source/Modeling/BMesh/Design>`_ .
+
+
+.. note::
+
+   **Disk** and **Radial** data is not exposed by the python api since this is for internal use only.
+
+
+.. warning::
+
+   This API is still in development and experimental, while we don't expect to see large changes,
+   many areas are not well tested yet and so its possible changes will be made that break scripts.
+
+   *Campbell Barton, 13, March 2012*
+
+
+.. todo::
+
+   * add access to BMesh **walkers**
+   * add access selection history (readonly access done)
+   * add a way to re-tessellate an editmode bmesh.
+
+
+Stand-Alone Module
+^^^^^^^^^^^^^^^^^^
+
+The bmesh module is written to be standalone except for :mod:`mathutils`
+which is used for vertex locations and normals.
+
+The only other exception to this are when converting mesh data to and from :class:`bpy.types.Mesh`.
+
+
+Mesh Access
+-----------
+
+There are 2 ways to access BMesh data, you can create a new BMesh by converting a mesh from
+:class:`bpy.types.BlendData.meshes` or by accessing the current edit mode mesh.
+see: :class:`bmesh.types.BMesh.from_mesh` and :mod:`bmesh.from_edit_mesh` respectively.
+
+When explicitly converting from mesh data python **owns** the data, that is to say - that the mesh only exists while
+python holds a reference to it, and the script is responsible for putting it back into a mesh data-block when the edits
+are done.
+
+Note that unlike :mod:`bpy`, a BMesh does not necessarily correspond to data in the currently open blend file,
+a BMesh can be created, edited and freed without the user ever seeing or having access to it.
+Unlike edit mode, the bmesh module can use multiple BMesh instances at once.
+
+Take care when dealing with multiple BMesh instances since the mesh data can use a lot of memory, while a mesh that
+python owns will be freed in when the script holds no references to it,
+its good practice to call :class:`bmesh.types.BMesh.free` which will remove all the mesh data immediately and disable
+further access.
+
+
+Keeping a Correct State
+-----------------------
+
+When modeling in blender there are certain assumptions made about the state of the mesh.
+
+* hidden geometry isn't selected.
+* when an edge is selected, its vertices's are selected too.
+* when a face is selected, its edges and vertices's are selected.
+* duplicate edges / faces don't exist.
+* faces have at least 3 vertices's.
+
+To give developers flexibility these conventions are not enforced,
+however tools must leave the mesh in a valid state else other tools may behave incorrectly.
+
+Any errors that arise from not following these conventions is considered a bug in the script,
+not a bug in blender.
+
+
+Selection / Flushing
+^^^^^^^^^^^^^^^^^^^^
+
+As mentioned above, it is possible to create an invalid selection state
+(by selecting a state and then de-selecting one of its vertices's for example), mostly the best way to solve this is to
+flush the selection after performing a series of edits. this validates the selection state.
+
+
+Example Script
+--------------
+
+.. literalinclude:: ../../../release/scripts/templates/bmesh_simple.py
+
+
+Module Functions
+----------------

doc/python_api/sphinx_doc_gen.py

@@ -37,6 +37,7 @@ API dump in RST files
   For quick builds:
     ./blender.bin -b -P doc/python_api/sphinx_doc_gen.py -- -q
 
+
 Sphinx: HTML generation
 -----------------------
   After you have built doc/python_api/sphinx-in (see above),
@@ -47,6 +48,7 @@ Sphinx: HTML generation
 
   This requires sphinx 1.0.7 to be installed.
 
+
 Sphinx: PDF generation
 ----------------------
   After you have built doc/python_api/sphinx-in (see above),
@@ -139,11 +141,11 @@ def handle_args():
                         help="Rewrite all rst files in sphinx-in/ (default=False)",
                         required=False)
 
-    parser.add_argument("-t", "--testdump",
+    parser.add_argument("-p", "--partial",
-                        dest="test_dump",
+                        dest="partial",
-                        default=False,
+                        type=str,
-                        action='store_true',
+                        default="",
-                        help="Dumps a small part of the API (default=False)",
+                        help="Use a wildcard to only build spesific module(s)",
                         required=False)
 
     parser.add_argument("-b", "--bpy",
@@ -173,7 +175,7 @@ sphinx-build doc/python_api/sphinx-in doc/python_api/sphinx-out
 """
 
 # Switch for quick testing so doc-builds don't take so long
-if not ARGS.test_dump:
+if not ARGS.partial:
     # full build
     FILTER_BPY_OPS = None
     FILTER_BPY_TYPES = None
@@ -181,6 +183,7 @@ if not ARGS.test_dump:
     EXCLUDE_MODULES = ()
 
 else:
+    # can manually edit this too:
     FILTER_BPY_OPS = ("import.scene", )  # allow
     FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID")  # allow
     EXCLUDE_INFO_DOCS = True
@@ -195,9 +198,9 @@ else:
         "bge.types",
         "bgl",
         "blf",
-        #"bmesh",
+        "bmesh",
-        #"bmesh.types",
+        "bmesh.types",
-        #"bmesh.utils",
+        "bmesh.utils",
         "bpy.app",
         "bpy.app.handlers",
         "bpy.context",
@@ -214,6 +217,22 @@ else:
         "mathutils.noise",
     )
 
+    # ------
+    # Filter
+    #
+    # TODO, support bpy.ops and bpy.types filtering
+    import fnmatch
+    m = None
+    EXCLUDE_MODULES = tuple([m for m in EXCLUDE_MODULES if not fnmatch.fnmatchcase(m, ARGS.partial)])
+    del m
+    del fnmatch
+
+    print("Partial Doc Build, Skipping: %s\n" % "\n                             ".join(sorted(EXCLUDE_MODULES)))
+
+    #
+    # done filtering
+    # --------------
+
 try:
     __import__("aud")
 except ImportError:
@@ -1527,6 +1546,9 @@ def copy_handwritten_rsts(basepath):
         "bge.constraints",
         "bgl",  # "Blender OpenGl wrapper"
         "gpu",  # "GPU Shader Module"
+
+        # includes...
+        "include__bmesh",
     ]
     for mod_name in handwritten_modules:
         if mod_name not in EXCLUDE_MODULES:

intern/ghost/GHOST_ISystem.h

@@ -82,7 +82,7 @@ class GHOST_IEventConsumer;
  * <li> OSX Carbon.</li>
  * <li> Windows.</li>
  * <li> X11.</li>
- * <li> SDL1.3 (experemental).</li>
+ * <li> SDL1.3 (experimental).</li>
  * <li> NULL (headless mode).</li>
  * </ul>
  *

source/blender/nodes/composite/nodes/node_composite_doubleEdgeMask.c

@@ -998,7 +998,7 @@ static void do_fillGradientBuffer(unsigned int rw, float *res, unsigned short *g
      purpose of GO for the proportion calculation.
 
      For the purposes of the minimun distance comparisons, we only check
-     the sums-of-squares against eachother, since they are in the same
+     the sums-of-squares against each other, since they are in the same
      mathematical sort-order as if we did go ahead and take square roots
 
      Loop through all gradient pixels.

source/blender/python/bmesh/bmesh_py_api.c

@@ -108,10 +108,7 @@ PyDoc_STRVAR(BPy_BM_doc,
 "* :mod:`bmesh.types`\n"
 "\n"
 "\n"
-"Example Script\n"
+".. include:: include__bmesh.rst\n"
-"--------------\n"
-"\n"
-".. literalinclude:: ../../../release/scripts/templates/bmesh_simple.py\n"
 );
 static struct PyModuleDef BPy_BM_module_def = {
 	PyModuleDef_HEAD_INIT,

source/blender/python/intern/bpy_rna.c

@@ -4524,7 +4524,7 @@ static struct PyMethodDef pyrna_struct_methods[] = {
 	{"type_recast", (PyCFunction)pyrna_struct_type_recast, METH_NOARGS, pyrna_struct_type_recast_doc},
 	{"__dir__", (PyCFunction)pyrna_struct_dir, METH_NOARGS, NULL},
 
-	/* experemental */
+	/* experimental */
 	{"callback_add", (PyCFunction)pyrna_callback_add, METH_VARARGS, NULL},
 	{"callback_remove", (PyCFunction)pyrna_callback_remove, METH_VARARGS, NULL},
 	{NULL, NULL, 0, NULL}

source/blender/python/mathutils/mathutils_Matrix.c

@@ -780,7 +780,7 @@ PyDoc_STRVAR(C_Matrix_Shear_doc,
 "   :arg size: The size of the shear matrix to construct [2, 4].\n"
 "   :type size: int\n"
 "   :arg factor: The factor of shear to apply. For a 3 or 4 *size* matrix\n"
-"      pass a pair of floats corrasponding with the *plane* axis.\n"
+"      pass a pair of floats corresponding with the *plane* axis.\n"
 "   :type factor: float or float pair\n"
 "   :return: A new shear matrix.\n"
 "   :rtype: :class:`Matrix`\n"

source/gameengine/Ketsji/KX_GameObject.cpp

@@ -1662,7 +1662,7 @@ PyAttributeDef KX_GameObject::Attributes[] = {
 	KX_PYATTRIBUTE_RO_FUNCTION("attrDict",	KX_GameObject, pyattr_get_attrDict),
 	KX_PYATTRIBUTE_RW_FUNCTION("color", KX_GameObject, pyattr_get_obcolor, pyattr_set_obcolor),
 	
-	/* Experemental, dont rely on these yet */
+	/* experimental, don't rely on these yet */
 	KX_PYATTRIBUTE_RO_FUNCTION("sensors",		KX_GameObject, pyattr_get_sensors),
 	KX_PYATTRIBUTE_RO_FUNCTION("controllers",	KX_GameObject, pyattr_get_controllers),
 	KX_PYATTRIBUTE_RO_FUNCTION("actuators",		KX_GameObject, pyattr_get_actuators),

source/gameengine/Ketsji/KX_GameObject.h

@@ -995,7 +995,7 @@ public:
 	static PyObject*	pyattr_get_obcolor(void *selv_v, const KX_PYATTRIBUTE_DEF *attrdef);
 	static int			pyattr_set_obcolor(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef, PyObject *value);
 	
-	/* Experemental! */
+	/* Experimental! */
 	static PyObject*	pyattr_get_sensors(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
 	static PyObject*	pyattr_get_controllers(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
 	static PyObject*	pyattr_get_actuators(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);