diff options
author | Campbell Barton <ideasman42@gmail.com> | 2012-03-21 09:33:37 +0400 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2012-03-21 09:33:37 +0400 |
commit | 9773f87891b58e91f46b3cfd3e6f4f50de5d9411 (patch) | |
tree | 38c74bc80c389d0224514a6b5eab74d72e14b57d /doc/python_api | |
parent | 1d5922fbaf1bf66a73761c0baceda3edca8211fe (diff) |
bmesh docs:
- add examples for custom-data access
- group BMesh types logically in docs
- added missing docstrings
needed to add grouping functionality to sphinx for this.
Diffstat (limited to 'doc/python_api')
-rw-r--r-- | doc/python_api/rst/include__bmesh.rst | 46 | ||||
-rw-r--r-- | doc/python_api/sphinx_doc_gen.py | 76 |
2 files changed, 109 insertions, 13 deletions
diff --git a/doc/python_api/rst/include__bmesh.rst b/doc/python_api/rst/include__bmesh.rst index 2481c4a739c..025788ae9f4 100644 --- a/doc/python_api/rst/include__bmesh.rst +++ b/doc/python_api/rst/include__bmesh.rst @@ -30,10 +30,19 @@ For an overview of BMesh data types and how they reference each other see: *Campbell Barton, 13, March 2012* -.. todo:: +.. warning:: + + TODO Items Are * add access to BMesh **walkers** * add a way to re-tessellate an editmode bmesh. + * add deform vert custom-data access. + + +Example Script +-------------- + +.. literalinclude:: ../../../release/scripts/templates/bmesh_simple.py Stand-Alone Module @@ -66,6 +75,35 @@ its good practice to call :class:`bmesh.types.BMesh.free` which will remove all further access. +CustomData Access +----------------- + +BMesh has a unified way to access mesh attributes such as UV's vertex colors, shape keys, edge crease etc. + +This works by having a **layers** property on bmesh data sequences to access the custom data layers which can then be +used to access the actual data on each vert/edge/face/loop. + +Here are some examples ... + +.. code-block:: python + + uv_lay = bm.loops.layers.uv.active + + for face in bm.faces: + for loop in f.loops: + uv = loop[uv_lay] + print("Loop UV: %f, %f" % (uv.x, uv.y)) + + +.. code-block:: python + + shape_lay = bm.verts.layers.shape["Key.001"] + + for vert in bm.verts: + shape = vert[shape_lay] + print("Vert Shape: %f, %f, %f" % (shape.x, shape.y, shape.z)) + + Keeping a Correct State ----------------------- @@ -92,11 +130,5 @@ As mentioned above, it is possible to create an invalid selection state 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 ---------------- diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index f698c28712f..e88c7f5e074 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -312,6 +312,36 @@ RNA_BLACKLIST = { "UserPreferencesSystem": {"language", } } +MODULE_GROUPING = { + "bmesh.types": ( + ("Base Mesh Type", '-'), + "BMesh", + ("Mesh Elements", '-'), + "BMVert", + "BMEdge", + "BMFace", + "BMLoop", + ("Sequence Accessors", '-'), + "BMElemSeq", + "BMVertSeq", + "BMEdgeSeq", + "BMFaceSeq", + "BMLoopSeq", + "BMIter", + ("Selection History", '-'), + "BMEditSelSeq", + "BMEditSelIter", + ("Custom-Data Layer Access", '-'), + "BMLayerAccessVert", + "BMLayerAccessEdge", + "BMLayerAccessFace", + "BMLayerAccessLoop", + "BMLayerCollection", + "BMLayerItem", + ("Custom-Data Layer Types", '-'), + "BMLoopUV" + ) + } # --------------------configure compile time options---------------------------- @@ -656,6 +686,29 @@ def pymodule2sphinx(basepath, module_name, module, title): if module_all: module_dir = module_all + # TODO - currently only used for classes + # grouping support + module_grouping = MODULE_GROUPING.get(module_name) + def module_grouping_index(name): + if module_grouping is not None: + try: + return module_grouping.index(name) + except ValueError: + pass + return -1 + + def module_grouping_heading(name): + if module_grouping is not None: + i = module_grouping_index(name) - 1 + if i >= 0 and type(module_grouping[i]) == tuple: + return module_grouping[i] + return None, None + + def module_grouping_sort_key(name): + return module_grouping_index(name) + # done grouping support + + file = open(filepath, "w", encoding="utf-8") fw = file.write @@ -805,8 +858,17 @@ def pymodule2sphinx(basepath, module_name, module, title): fw("\n") ''' + if module_grouping is not None: + classes.sort(key=lambda pair: module_grouping_sort_key(pair[0])) + # write collected classes now for (type_name, value) in classes: + + if module_grouping is not None: + heading, heading_char = module_grouping_heading(type_name) + if heading: + fw(title_string(heading, heading_char)) + # May need to be its own function fw(".. class:: %s\n\n" % type_name) if value.__doc__: @@ -1412,7 +1474,7 @@ def write_rst_contents(basepath): fw(".. toctree::\n") fw(" :maxdepth: 1\n\n") - app_modules = [ + app_modules = ( "bpy.context", # note: not actually a module "bpy.data", # note: not actually a module "bpy.ops", @@ -1425,8 +1487,9 @@ def write_rst_contents(basepath): "bpy.app.handlers", # C modules - "bpy.props" - ] + "bpy.props", + ) + for mod in app_modules: if mod not in EXCLUDE_MODULES: fw(" %s\n\n" % mod) @@ -1435,14 +1498,15 @@ def write_rst_contents(basepath): fw(".. toctree::\n") fw(" :maxdepth: 1\n\n") - standalone_modules = [ + standalone_modules = ( # mathutils "mathutils", "mathutils.geometry", "mathutils.noise", # misc "bgl", "blf", "gpu", "aud", "bpy_extras", # bmesh - "bmesh", "bmesh.types", "bmesh.utils" - ] + "bmesh", "bmesh.types", "bmesh.utils", + ) + for mod in standalone_modules: if mod not in EXCLUDE_MODULES: fw(" %s\n\n" % mod) |