[Bf-blender-cvs] [18f228d] master: update hand written rst docs

Thu Jun 18 00:05:12 CEST 2015

Commit: 18f228d593123cf7fd6eef7ceda27a1c092e1df8
Author: Campbell Barton
Date:   Thu Jun 18 07:52:52 2015 +1000
Branches: master
https://developer.blender.org/rB18f228d593123cf7fd6eef7ceda27a1c092e1df8

update hand written rst docs

- minor corrections
- link to new manual
- wrap lines at 120

===================================================================

M	doc/python_api/rst/info_api_reference.rst
M	doc/python_api/rst/info_best_practice.rst
M	doc/python_api/rst/info_overview.rst
M	doc/python_api/rst/info_quickstart.rst
M	doc/python_api/rst/info_tips_and_tricks.rst
M	doc/python_api/rst/info_tutorial_addon.rst
M	release/scripts/modules/bpy_extras/object_utils.py

===================================================================

diff --git a/doc/python_api/rst/info_api_reference.rst b/doc/python_api/rst/info_api_reference.rst
index ddee46d..43469fc 100644
--- a/doc/python_api/rst/info_api_reference.rst
+++ b/doc/python_api/rst/info_api_reference.rst
@@ -121,7 +121,7 @@ Here are some more complex examples:
    bpy.context.scene.render.layers["RenderLayer"].samples
 
    # access to the current weight paint brush size
-   bpy.context.tool_settings.weight_paint.brush.size  
+   bpy.context.tool_settings.weight_paint.brush.size
 
    # check if the window is fullscreen
    bpy.context.window.screen.show_fullscreen
@@ -141,15 +141,16 @@ When starting out scripting you will often run into the problem where you're not
 
 There are a few ways to do this.
 
-- Use the Python console's auto-complete to inspect properties. *This can be hit-and-miss but has the advantage
+- Use the Python console's auto-complete to inspect properties.
+  *This can be hit-and-miss but has the advantage
   that you can easily see the values of properties and assign them to interactively see the results.*
+- Copy the Data-Path from the user interface.
+  *Explained further in :ref:`Copy Data Path <info_data_path_copy>`*
+- Using the documentation to follow references.
+  *Explained further in :ref:`Indirect Data Access <info_data_path_indirect>`*
 
-- Copy the Data-Path from the user interface. *Explained further in :ref:`Copy Data Path <info_data_path_copy>`*
 
-- Using the documentation to follow references. *Explained further in :ref:`Indirect Data Access <info_data_path_indirect>`*
-
-
-.. _info_data_path_copy
+.. _info_data_path_copy:
 
 Copy Data Path
 --------------
@@ -172,7 +173,8 @@ you won't be doing collection look-ups on every access and typically you'll want
 then access each :class:`bpy.types.ID` instance by name.
 
 
-Type in the ID path into a Python console :mod:`bpy.context.active_object`. Include the trailing dot and don't hit "enter", yet. 
+Type in the ID path into a Python console :mod:`bpy.context.active_object`.
+Include the trailing dot and don't hit "enter", yet.
 
 Now right-click on the button and select **Copy Data Path**, then paste the result into the console.
 
@@ -191,7 +193,7 @@ Hit "enter" and you'll get the current value of 1. Now try changing the value to
 You can see the value update in the Subdivision-Surface modifier's UI as well as the cube.
 
 
-.. _info_data_path_indirect
+.. _info_data_path_indirect:
 
 Indirect Data Access
 --------------------
@@ -201,32 +203,24 @@ For this example we'll go over something more involved, showing the steps to acc
 Lets say we want to access the texture of a brush via Python, to adjust its ``contrast`` for example.
 
 - Start in the default scene and enable 'Sculpt' mode from the 3D-View header.
-
 - From the toolbar expand the **Texture** panel and add a new texture.
-
   *Notice the texture button its self doesn't have very useful links (you can check the tool-tips).*
-
 - The contrast setting isn't exposed in the sculpt toolbar, so view the texture in the properties panel...
 
   - In the properties button select the Texture context.
-
   - Select the Brush icon to show the brush texture.
-
-  - Expand the **Colors** panel to locate the **Contrast** button.
-
-- Right click on the contrast button and select **Online Python Reference** This takes you to ``bpy.types.Texture.contrast``
-
-- Now we can see that ``contrast`` is a property of texture, so next we'll check on how to access the texture from the brush.
-
+  - Expand the *Colors* panel to locate the *Contrast* button.
+- Right click on the contrast button and select **Online Python Reference**
+  This takes you to ``bpy.types.Texture.contrast``
+- Now we can see that ``contrast`` is a property of texture,
+  so next we'll check on how to access the texture from the brush.
 - Check on the **References** at the bottom of the page, sometimes there are many references, and it may take
   some guess work to find the right one, but in this case its obviously ``Brush.texture``.
 
   *Now we know that the texture can be accessed from* ``bpy.data.brushes["BrushName"].texture``
   *but normally you won't want to access the brush by name, so we'll see now to access the active brush instead.*
-
 - So the next step is to check on where brushes are accessed from via the **References**.
   In this case there is simply ``bpy.context.brush`` which is all we need.
-  
 
 Now you can use the Python console to form the nested properties needed to access brush textures contrast,
 logically we now know.
@@ -282,7 +276,8 @@ are interested to check on the source code.
 
 .. note::
 
-   Not all operators can be called usefully from Python, for more on this see :ref:`using operators <using_operators>`.
+   Not all operators can be called usefully from Python,
+   for more on this see :ref:`using operators <using_operators>`.
 
 
 Info View
@@ -294,7 +289,8 @@ This is located above the file-menu which can be dragged down to display its con
 Select the **Script** screen that comes default with Blender to see its output.
 You can perform some actions and see them show up - delete a vertex for example.
 
-Each entry can be selected (Right-Mouse-Button), then copied :kbd:`Control-C`, usually to paste in the text editor or python console.
+Each entry can be selected (Right-Mouse-Button),
+then copied :kbd:`Control-C`, usually to paste in the text editor or python console.
 
 .. note::
 
diff --git a/doc/python_api/rst/info_best_practice.rst b/doc/python_api/rst/info_best_practice.rst
index 1e12dab..8c5ae33 100644
--- a/doc/python_api/rst/info_best_practice.rst
+++ b/doc/python_api/rst/info_best_practice.rst
@@ -1,16 +1,20 @@
+
 *************
 Best Practice
 *************
 
-When writing your own scripts python is great for new developers to pick up and become productive, but you can also pick up odd habits or at least write scripts that are not easy for others to understand.
+When writing your own scripts python is great for new developers to pick up and become productive,
+but you can also pick up odd habits or at least write scripts that are not easy for others to understand.
 
-For your own work this is of course fine, but if you want to collaborate with others or have your work included with blender there are practices we encourage.
+For your own work this is of course fine,
+but if you want to collaborate with others or have your work included with blender there are practices we encourage.
 
 
 Style Conventions
 =================
 
-For Blender/Python development we have chosen to follow python suggested style guide to avoid mixing styles amongst our own scripts and make it easier to use python scripts from other projects.
+For Blender/Python development we have chosen to follow python suggested style guide to avoid mixing styles
+amongst our own scripts and make it easier to use python scripts from other projects.
 
 Using our style guide for your own scripts makes it easier if you eventually want to contribute them to blender.
 
@@ -18,22 +22,17 @@ This style guide is known as pep8 and can be found `here <http://www.python.org/
 
 A brief listing of pep8 criteria.
 
-* camel caps for class names: MyClass
-
-* all lower case underscore separated module names: my_module
-
-* indentation of 4 spaces (no tabs)
-
-* spaces around operators. ``1 + 1``, not ``1+1``
-
-* only use explicit imports, (no importing '*')
-
-* don't use single line: ``if val: body``, separate onto 2 lines instead.
+- camel caps for class names: MyClass
+- all lower case underscore separated module names: my_module
+- indentation of 4 spaces (no tabs)
+- spaces around operators. ``1 + 1``, not ``1+1``
+- only use explicit imports, (no importing ``*``)
+- don't use single line: ``if val: body``, separate onto 2 lines instead.
 
 
 As well as pep8 we have other conventions used for blender python scripts.
 
-* Use single quotes for enums, and double quotes for strings.
+- Use single quotes for enums, and double quotes for strings.
 
   Both are of course strings but in our internal API enums are unique items from a limited set. eg.
 
@@ -42,9 +41,11 @@ As well as pep8 we have other conventions used for blender python scripts.
      bpy.context.scene.render.image_settings.file_format = 'PNG'
      bpy.context.scene.render.filepath = "//render_out"
 
-* pep8 also defines that lines should not exceed 79 characters, we felt this is too restrictive so this is optional per script.
+- pep8 also defines that lines should not exceed 79 characters,
+  we felt this is too restrictive so this is optional per script.
 
-Periodically we run checks for pep8 compliance on blender scripts, for scripts to be included in this check add this line as a comment at the top of the script.
+Periodically we run checks for pep8 compliance on blender scripts,
+for scripts to be included in this check add this line as a comment at the top of the script.
 
 ``# <pep8 compliant>``
 
@@ -58,72 +59,75 @@ User Interface Layout
 
 Some notes to keep in mind when writing UI layouts:
 
-* UI code is quite simple. Layout declarations are there to easily create a decent layout. 
+- UI code is quite simple. Layout declarations are there to easily create a decent layout.
+
+  General rule here: If you need more code for the layout declaration,
+  then for the actual properties, you do it wrong.
 
-  General rule here: If you need more code for the layout declaration, then for the actual properties, you do it wrong. 
-  
 Example layouts:
 
-* layout()
+- layout()
+
+  The basic layout is a simple Top -> Bottom layout.
 
-  The basic layout is a simple Top -> Bottom layout. 
-  
   .. code-block:: python
 
-	 layout.prop()
-	 layout.prop()
+        layout.prop()
+        layout.prop()
+
+- layout.row()
 
-* layout.row()
+  Use row(), when you want more than 1 property in one line.
 
-  Use row(), when you want more than 1 property in one line. 
-  
   .. code-block:: python
-	 
-	 row = layout.row()
-	 row.prop()
-	 row.prop()
 
-* layout.column()
+        row = layout.row()
+        row.prop()
+        row.prop()
+
+- layout.column()
 
   Use column(), when you want your properties in a column.
-  
+
   .. code-block:: python
-  
-	 col = layout.column()
-	 col

@@ Diff output truncated at 10240 characters. @@


