From f184202a9af1599e8d504e0c2991a829da6fae48 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Tue, 8 Sep 2015 14:30:05 +1000 Subject: Cleanup: API docs --- doc/python_api/examples/aud.py | 1 + doc/python_api/examples/bge.texture.1.py | 1 + doc/python_api/examples/bpy.app.handlers.py | 1 + doc/python_api/examples/bpy.ops.1.py | 5 +++-- doc/python_api/examples/bpy.ops.py | 22 +++++++++++----------- .../examples/bpy.types.AddonPreferences.1.py | 3 ++- doc/python_api/examples/bpy.types.Menu.1.py | 1 + doc/python_api/examples/bpy.types.Menu.2.py | 1 + doc/python_api/examples/bpy.types.Menu.py | 1 + doc/python_api/examples/bpy.types.Mesh.py | 8 ++++---- doc/python_api/examples/bpy.types.NodeTree.py | 1 + doc/python_api/examples/bpy.types.Object.py | 1 + doc/python_api/examples/bpy.types.Operator.1.py | 1 + doc/python_api/examples/bpy.types.Operator.2.py | 2 +- doc/python_api/examples/bpy.types.Operator.3.py | 1 + doc/python_api/examples/bpy.types.Operator.4.py | 1 + doc/python_api/examples/bpy.types.Operator.5.py | 7 ++++--- doc/python_api/examples/bpy.types.Operator.py | 1 + doc/python_api/examples/bpy.types.Panel.1.py | 1 + doc/python_api/examples/bpy.types.Panel.py | 1 + doc/python_api/examples/bpy.types.UIList.2.py | 3 ++- 21 files changed, 41 insertions(+), 23 deletions(-) diff --git a/doc/python_api/examples/aud.py b/doc/python_api/examples/aud.py index 2c74d6a0eb1..bbe97168efe 100644 --- a/doc/python_api/examples/aud.py +++ b/doc/python_api/examples/aud.py @@ -1,6 +1,7 @@ """ Basic Sound Playback ++++++++++++++++++++ + This script shows how to use the classes: :class:`Device`, :class:`Factory` and :class:`Handle`. """ diff --git a/doc/python_api/examples/bge.texture.1.py b/doc/python_api/examples/bge.texture.1.py index bee1f251afa..732c786c667 100644 --- a/doc/python_api/examples/bge.texture.1.py +++ b/doc/python_api/examples/bge.texture.1.py @@ -1,6 +1,7 @@ """ Texture Replacement +++++++++++++++++++ + Example of how to replace a texture in game with an external image. ``createTexture()`` and ``removeTexture()`` are to be called from a module Python Controller. diff --git a/doc/python_api/examples/bpy.app.handlers.py b/doc/python_api/examples/bpy.app.handlers.py index 57b209e15f0..078f9df77f2 100644 --- a/doc/python_api/examples/bpy.app.handlers.py +++ b/doc/python_api/examples/bpy.app.handlers.py @@ -1,6 +1,7 @@ """ Basic Handler Example +++++++++++++++++++++ + This script shows the most simple example of adding a handler. """ diff --git a/doc/python_api/examples/bpy.ops.1.py b/doc/python_api/examples/bpy.ops.1.py index a00dbdafb90..b4137e5c740 100644 --- a/doc/python_api/examples/bpy.ops.1.py +++ b/doc/python_api/examples/bpy.ops.1.py @@ -7,8 +7,9 @@ act on specified rather than the selected or active data, or to execute an operator in the different part of the user interface. The context overrides are passed as a dictionary, with keys matching the context -member names in bpy.context. For example to override bpy.context.active_object, -you would pass {'active_object': object}. +member names in bpy.context. +For example to override ``bpy.context.active_object``, +you would pass ``{'active_object': object}``. """ # remove all objects in scene rather than the selected ones diff --git a/doc/python_api/examples/bpy.ops.py b/doc/python_api/examples/bpy.ops.py index 9964ad915bf..76c494ad4f5 100644 --- a/doc/python_api/examples/bpy.ops.py +++ b/doc/python_api/examples/bpy.ops.py @@ -3,21 +3,21 @@ Calling Operators ----------------- Provides python access to calling operators, this includes operators written in -C, Python or Macros. +C, Python or macros. Only keyword arguments can be used to pass operator properties. -Operators don't have return values as you might expect, instead they return a -set() which is made up of: {'RUNNING_MODAL', 'CANCELLED', 'FINISHED', -'PASS_THROUGH'}. -Common return values are {'FINISHED'} and {'CANCELLED'}. +Operators don't have return values as you might expect, +instead they return a set() which is made up of: +``{'RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH'}``. +Common return values are ``{'FINISHED'}`` and ``{'CANCELLED'}``. -Calling an operator in the wrong context will raise a RuntimeError, +Calling an operator in the wrong context will raise a ``RuntimeError``, there is a poll() method to avoid this problem. -Note that the operator ID (bl_idname) in this example is 'mesh.subdivide', -'bpy.ops' is just the access path for python. +Note that the operator ID (bl_idname) in this example is ``mesh.subdivide``, +``bpy.ops`` is just the access path for python. Keywords and Positional Arguments @@ -32,9 +32,9 @@ There are 3 optional positional arguments (documented in detail below). bpy.ops.test.operator(override_context, execution_context, undo) -* override_context - dict type -* execution_context - string (enum) -* undo - boolean +- override_context - ``dict`` type. +- execution_context - ``str`` (enum). +- undo - ``bool`` type. Each of these arguments is optional, but must be given in the order above. diff --git a/doc/python_api/examples/bpy.types.AddonPreferences.1.py b/doc/python_api/examples/bpy.types.AddonPreferences.1.py index 73f90acb3fa..7a065dbf6a5 100644 --- a/doc/python_api/examples/bpy.types.AddonPreferences.1.py +++ b/doc/python_api/examples/bpy.types.AddonPreferences.1.py @@ -8,7 +8,8 @@ bl_info = { "warning": "", "wiki_url": "", "tracker_url": "", - "category": "Object"} + "category": "Object", + } import bpy diff --git a/doc/python_api/examples/bpy.types.Menu.1.py b/doc/python_api/examples/bpy.types.Menu.1.py index e82bf398e35..8ccc1123c35 100644 --- a/doc/python_api/examples/bpy.types.Menu.1.py +++ b/doc/python_api/examples/bpy.types.Menu.1.py @@ -1,6 +1,7 @@ """ Submenus ++++++++ + This menu demonstrates some different functions. """ import bpy diff --git a/doc/python_api/examples/bpy.types.Menu.2.py b/doc/python_api/examples/bpy.types.Menu.2.py index 26409f12f45..86288b5b1c5 100644 --- a/doc/python_api/examples/bpy.types.Menu.2.py +++ b/doc/python_api/examples/bpy.types.Menu.2.py @@ -1,6 +1,7 @@ """ Extending Menus +++++++++++++++ + When creating menus for addons you can't reference menus in Blender's default scripts. Instead, the addon can add menu items to existing menus. diff --git a/doc/python_api/examples/bpy.types.Menu.py b/doc/python_api/examples/bpy.types.Menu.py index e10e44f108e..c2162444055 100644 --- a/doc/python_api/examples/bpy.types.Menu.py +++ b/doc/python_api/examples/bpy.types.Menu.py @@ -1,6 +1,7 @@ """ Basic Menu Example ++++++++++++++++++ + Here is an example of a simple menu. Menus differ from panels in that they must reference from a header, panel or another menu. diff --git a/doc/python_api/examples/bpy.types.Mesh.py b/doc/python_api/examples/bpy.types.Mesh.py index 19ccd177d64..68cc42ec6bf 100644 --- a/doc/python_api/examples/bpy.types.Mesh.py +++ b/doc/python_api/examples/bpy.types.Mesh.py @@ -7,10 +7,10 @@ for more flexible mesh editing from python see :mod:`bmesh`. Blender stores 4 main arrays to define mesh geometry. -* :class:`Mesh.vertices` (3 points in space) -* :class:`Mesh.edges` (reference 2 vertices) -* :class:`Mesh.loops` (reference a single vertex and edge) -* :class:`Mesh.polygons`: (reference a range of loops) +- :class:`Mesh.vertices` (3 points in space) +- :class:`Mesh.edges` (reference 2 vertices) +- :class:`Mesh.loops` (reference a single vertex and edge) +- :class:`Mesh.polygons`: (reference a range of loops) Each polygon reference a slice in the loop array, this way, polygons do not store vertices or corner data such as UV's directly, diff --git a/doc/python_api/examples/bpy.types.NodeTree.py b/doc/python_api/examples/bpy.types.NodeTree.py index 401b3a01ae0..da2986636ea 100644 --- a/doc/python_api/examples/bpy.types.NodeTree.py +++ b/doc/python_api/examples/bpy.types.NodeTree.py @@ -1,6 +1,7 @@ """ Poll Function +++++++++++++++ + The :class:`NodeTree.poll` function determines if a node tree is visible in the given context (similar to how :class:`Panel.poll` and :class:`Menu.poll` define visibility). If it returns False, diff --git a/doc/python_api/examples/bpy.types.Object.py b/doc/python_api/examples/bpy.types.Object.py index 2ddce248a5b..90c50bcfad7 100644 --- a/doc/python_api/examples/bpy.types.Object.py +++ b/doc/python_api/examples/bpy.types.Object.py @@ -1,6 +1,7 @@ """ Basic Object Operations Example +++++++++++++++++++++++++++++++ + This script demonstrates basic operations on object like creating new object, placing it into scene, selecting it and making it active. """ diff --git a/doc/python_api/examples/bpy.types.Operator.1.py b/doc/python_api/examples/bpy.types.Operator.1.py index f007cdfa0a7..1ba13c040ba 100644 --- a/doc/python_api/examples/bpy.types.Operator.1.py +++ b/doc/python_api/examples/bpy.types.Operator.1.py @@ -1,6 +1,7 @@ """ Invoke Function +++++++++++++++ + :class:`Operator.invoke` is used to initialize the operator from the context at the moment the operator is called. invoke() is typically used to assign properties which are then used by diff --git a/doc/python_api/examples/bpy.types.Operator.2.py b/doc/python_api/examples/bpy.types.Operator.2.py index 39ff5caae8a..e2f9a3a84c4 100644 --- a/doc/python_api/examples/bpy.types.Operator.2.py +++ b/doc/python_api/examples/bpy.types.Operator.2.py @@ -4,7 +4,7 @@ Calling a File Selector This example shows how an operator can use the file selector. Notice the invoke function calls a window manager method and returns -RUNNING_MODAL, this means the file selector stays open and the operator does not +``{'RUNNING_MODAL'}``, this means the file selector stays open and the operator does not exit immediately after invoke finishes. The file selector runs the operator, calling :class:`Operator.execute` when the diff --git a/doc/python_api/examples/bpy.types.Operator.3.py b/doc/python_api/examples/bpy.types.Operator.3.py index 7fdccd81379..d59c816319d 100644 --- a/doc/python_api/examples/bpy.types.Operator.3.py +++ b/doc/python_api/examples/bpy.types.Operator.3.py @@ -1,6 +1,7 @@ """ Dialog Box ++++++++++ + This operator uses its :class:`Operator.invoke` function to call a popup. """ import bpy diff --git a/doc/python_api/examples/bpy.types.Operator.4.py b/doc/python_api/examples/bpy.types.Operator.4.py index 885ed857842..e5bc6e5c70d 100644 --- a/doc/python_api/examples/bpy.types.Operator.4.py +++ b/doc/python_api/examples/bpy.types.Operator.4.py @@ -1,6 +1,7 @@ """ Custom Drawing ++++++++++++++ + By default operator properties use an automatic user interface layout. If you need more control you can create your own layout with a :class:`Operator.draw` function. diff --git a/doc/python_api/examples/bpy.types.Operator.5.py b/doc/python_api/examples/bpy.types.Operator.5.py index 78030c7d7c4..310eeceadf3 100644 --- a/doc/python_api/examples/bpy.types.Operator.5.py +++ b/doc/python_api/examples/bpy.types.Operator.5.py @@ -1,8 +1,9 @@ """ Modal Execution +++++++++++++++ + This operator defines a :class:`Operator.modal` function which running, -handling events until it returns {'FINISHED'} or {'CANCELLED'}. +handling events until it returns ``{'FINISHED'}`` or ``{'CANCELLED'}``. Grab, Rotate, Scale and Fly-Mode are examples of modal operators. They are especially useful for interactive tools, @@ -10,9 +11,9 @@ your operator can have its own state where keys toggle options as the operator runs. :class:`Operator.invoke` is used to initialize the operator as being by -returning {'RUNNING_MODAL'}, initializing the modal loop. +returning ``{'RUNNING_MODAL'}``, initializing the modal loop. -Notice __init__() and __del__() are declared. +Notice ``__init__()`` and ``__del__()`` are declared. For other operator types they are not useful but for modal operators they will be called before the :class:`Operator.invoke` and after the operator finishes. """ diff --git a/doc/python_api/examples/bpy.types.Operator.py b/doc/python_api/examples/bpy.types.Operator.py index 0981712e1ff..4baa9380aa6 100644 --- a/doc/python_api/examples/bpy.types.Operator.py +++ b/doc/python_api/examples/bpy.types.Operator.py @@ -1,6 +1,7 @@ """ Basic Operator Example ++++++++++++++++++++++ + This script shows simple operator which prints a message. Since the operator only has an :class:`Operator.execute` function it takes no diff --git a/doc/python_api/examples/bpy.types.Panel.1.py b/doc/python_api/examples/bpy.types.Panel.1.py index fbcdae8baeb..13a9f53fa7b 100644 --- a/doc/python_api/examples/bpy.types.Panel.1.py +++ b/doc/python_api/examples/bpy.types.Panel.1.py @@ -1,6 +1,7 @@ """ Simple Object Panel +++++++++++++++++++ + This panel has a :class:`Panel.poll` and :class:`Panel.draw_header` function, even though the contents is basic this closely resembles blenders panels. """ diff --git a/doc/python_api/examples/bpy.types.Panel.py b/doc/python_api/examples/bpy.types.Panel.py index 1f64b953786..98187832b56 100644 --- a/doc/python_api/examples/bpy.types.Panel.py +++ b/doc/python_api/examples/bpy.types.Panel.py @@ -1,6 +1,7 @@ """ Basic Panel Example +++++++++++++++++++ + This script is a simple panel which will draw into the object properties section. diff --git a/doc/python_api/examples/bpy.types.UIList.2.py b/doc/python_api/examples/bpy.types.UIList.2.py index feed263b2e7..a02a0530a66 100644 --- a/doc/python_api/examples/bpy.types.UIList.2.py +++ b/doc/python_api/examples/bpy.types.UIList.2.py @@ -1,7 +1,8 @@ """ Advanced UIList Example - Filtering and Reordering ++++++++++++++++++++++++++++++++++++++++++++++++++ -This script is an extended version of the UIList subclass used to show vertex groups. It is not used 'as is', + +This script is an extended version of the ``UIList`` subclass used to show vertex groups. It is not used 'as is', because iterating over all vertices in a 'draw' function is a very bad idea for UI performances! However, it's a good example of how to create/use filtering/reordering callbacks. """ -- cgit v1.2.3