[Bf-blender-cvs] [127a754615e] master: PyAPI: Remove addon tutorial
Aaron Carlisle
noreply at git.blender.org
Fri Jun 16 04:01:43 CEST 2017
Commit: 127a754615efff02669a9afb50c2d44f6b354403
Author: Aaron Carlisle
Date: Thu Jun 15 13:00:58 2017 -0400
Branches: master
https://developer.blender.org/rB127a754615efff02669a9afb50c2d44f6b354403
PyAPI: Remove addon tutorial
This page now lives at https://docs.blender.org/manual/en/dev/advanced/scripting/addon_tutorial.html
===================================================================
D doc/python_api/rst/info_tutorial_addon.rst
M doc/python_api/sphinx_doc_gen.py
===================================================================
diff --git a/doc/python_api/rst/info_tutorial_addon.rst b/doc/python_api/rst/info_tutorial_addon.rst
deleted file mode 100644
index 92fbf9b8787..00000000000
--- a/doc/python_api/rst/info_tutorial_addon.rst
+++ /dev/null
@@ -1,635 +0,0 @@
-
-Add-on Tutorial
-###############
-
-************
-Introduction
-************
-
-
-Intended Audience
-=================
-
-This tutorial is designed to help technical artists or developers learn to extend Blender.
-An understanding of the basics of Python is expected for those working through this tutorial.
-
-
-Prerequisites
--------------
-
-Before going through the tutorial you should...
-
-- Familiarity with the basics of working in Blender.
-- Know how to run a script in Blender's text editor (as documented in the quick-start)
-- Have an understanding of Python primitive types (int, boolean, string, list, tuple, dictionary, and set).
-- Be familiar with the concept of Python modules.
-- Basic understanding of classes (object orientation) in Python.
-
-
-Suggested reading before starting this tutorial.
-
-- `Dive Into Python <http://getpython3.com/diveintopython3/index.html>`_ sections (1, 2, 3, 4, and 7).
-- :ref:`Blender API Quickstart <info_quickstart>`
- to help become familiar with Blender/Python basics.
-
-
-To best troubleshoot any error message Python prints while writing scripts you run blender with from a terminal,
-see :ref:`Use The Terminal <use_the_terminal>`.
-
-
-Documentation Links
-===================
-
-While going through the tutorial you may want to look into our reference documentation.
-
-- :ref:`Blender API Overview <info_overview>`. -
- *This document is rather detailed but helpful if you want to know more on a topic.*
-- :mod:`bpy.context` api reference. -
- *Handy to have a list of available items your script may operate on.*
-- :class:`bpy.types.Operator`. -
- *The following add-ons define operators, these docs give details and more examples of operators.*
-
-
-*******
-Add-ons
-*******
-
-What is an Add-on?
-==================
-
-An add-on is simply a Python module with some additional requirements so Blender can display it in a list with useful
-information.
-
-To give an example, here is the simplest possible add-on.
-
-.. code-block:: python
-
- bl_info = {"name": "My Test Add-on", "category": "Object"}
- def register():
- print("Hello World")
- def unregister():
- print("Goodbye World")
-
-
-- ``bl_info`` is a dictionary containing add-on metadata such as the title,
- version and author to be displayed in the user preferences add-on list.
-- ``register`` is a function which only runs when enabling the add-on,
- this means the module can be loaded without activating the add-on.
-- ``unregister`` is a function to unload anything setup by ``register``, this is called when the add-on is disabled.
-
-
-Notice this add-on does not do anything related to Blender, (the :mod:`bpy` module is not imported for example).
-
-This is a contrived example of an add-on that serves to illustrate the point
-that the base requirements of an add-on are simple.
-
-An add-on will typically register operators, panels, menu items etc, but its worth noting that _any_ script can do this,
-when executed from the text editor or even the interactive console - there is nothing inherently different about an
-add-on that allows it to integrate with Blender, such functionality is just provided by the :mod:`bpy` module for any
-script to access.
-
-So an add-on is just a way to encapsulate a Python module in a way a user can easily utilize.
-
-.. note::
-
- Running this script within the text editor won't print anything,
- to see the output it must be installed through the user preferences.
- Messages will be printed when enabling and disabling.
-
-
-Your First Add-on
-=================
-
-The simplest possible add-on above is useful as an example but not much else.
-This next add-on is simple but shows how to integrate a script into Blender using an ``Operator``
-which is the typical way to define a tool accessed from menus, buttons and keyboard shortcuts.
-
-For the first example we will make a script that simply moves all objects in a scene.
-
-
-Write The Script
-----------------
-
-Add the following script to the text editor in Blender.
-
-.. code-block:: python
-
- import bpy
-
- scene = bpy.context.scene
- for obj in scene.objects:
- obj.location.x += 1.0
-
-
-Click the :ref:`Run Script button <blender_manual:editors-text-run-script>`,
-all objects in the active scene are moved by 1.0 Blender unit.
-
-
-Write the Add-on (Simple)
--------------------------
-
-This add-on takes the body of the script above, and adds them to an operator's ``execute()`` function.
-
-
-.. code-block:: python
-
- bl_info = {
- "name": "Move X Axis",
- "category": "Object",
- }
-
- import bpy
-
-
- class ObjectMoveX(bpy.types.Operator):
- """My Object Moving Script""" # blender will use this as a tooltip for menu items and buttons.
- bl_idname = "object.move_x" # unique identifier for buttons and menu items to reference.
- bl_label = "Move X by One" # display name in the interface.
- bl_options = {'REGISTER', 'UNDO'} # enable undo for the operator.
-
- def execute(self, context): # execute() is called by blender when running the operator.
-
- # The original script
- scene = context.scene
- for obj in scene.objects:
- obj.location.x += 1.0
-
- return {'FINISHED'} # this lets blender know the operator finished successfully.
-
- def register():
- bpy.utils.register_class(ObjectMoveX)
-
-
- def unregister():
- bpy.utils.unregister_class(ObjectMoveX)
-
-
- # This allows you to run the script directly from blenders text editor
- # to test the add-on without having to install it.
- if __name__ == "__main__":
- register()
-
-
-.. note::
-
- ``bl_info`` is split across multiple lines, this is just a style convention used to more easily add items.
-
-.. note::
-
- Rather than using ``bpy.context.scene``, we use the ``context.scene`` argument passed to ``execute()``.
- In most cases these will be the same however in some cases operators will be passed a custom context
- so script authors should prefer the ``context`` argument passed to operators.
-
-To test the script you can copy and paste this into Blender text editor and run it, this will execute the script
-directly and call register immediately.
-
-However running the script wont move any objects, for this you need to execute the newly registered operator.
-
-.. image:: spacebar.png
- :width: 924px
- :align: center
- :height: 574px
- :alt: Spacebar
-
-Do this by pressing :kbd:`Spacebar` to bring up the operator search dialog and type in
-"Move X by One" (the ``bl_label``), then :kbd:`Enter`.
-
-
-
-The objects should move as before.
-
-*Keep this add-on open in Blender for the next step - Installing.*
-
-
-Install The Add-on
-------------------
-
-Once you have your add-on within in Blender's text editor,
-you will want to be able to install it so it can be enabled in the user preferences to load on startup.
-
-Even though the add-on above is a test, lets go through the steps anyway so you know how to do it for later.
-
-To install the Blender text as an add-on you will first have to save it to disk, take care to obey the naming
-restrictions that apply to Python modules and end with a ``.py`` extension.
-
-Once the file is on disk, you can install it as you would for an add-on downloaded online.
-
-Open the user :menuselection:`File --> User Preferences`,
-Select the *Add-on* section, press *Install Add-on...* and select the file.
-
-Now the add-on will be listed and you can enable it by pressing the check-box,
-if you want it to be enabled on restart, press *Save as Default*.
-
-.. note::
-
- The destination of the add-on depends on your Blender configuration.
- When installing an add-on the source and destination path are printed in the console.
- You can also find add-on path locations by running this in the Python console.
-
- .. code-block:: python
-
- import addon_utils
- print(addon_utils.paths())
-
- More is written on this topic here:
- :ref:`Directory Layout <blender_manual:getting-started_installing-config-directories>`.
-
-
-Your Second Add-on
-==================
-
-For our second add-on, we will focus on object instancing - this is - to make linked copies of an object in a
-similar way to what you may have seen with the array modifier.
-
-
-Write The Script
-----------------
-
-As before, first we will start with a script, develop it, then convert into an add-on.
-
-.. code-block:: python
-
- import bpy
- from bpy import context
-
- # Get the current scene
- scene = context.scene
-
- # Get the 3D cursor
- cursor = scene.cursor_location
-
- # Get the active object (assume we have one)
- obj = scene.objects.active
-
- # Now make a copy of the object
- obj_new = obj.copy()
-
- # The object won't automatically get into a new scene
- scene.objects.link(obj_new)
-
- # Now we can place the object
- obj_new.location = cursor
-
-
-Now try copy this script into Blender and run it on the default cube.
-Make sure you click to move the 3D cursor before running as the duplicate will appear at the cursor's location.
-
-
-... go off and test ...
-
-
-After running, notice that when you go into edit-mode to change the cube - all of the copies change,
-in Blender this is known as *Linked-Duplicates*.
-
-
-Next, we're going to do this in a loop, to make an array of objects between the active object and the cursor.
-
-
-.. code-block:: python
-
- import bpy
- from bpy import context
-
- scene = context.scene
- cursor = scene.cursor_location
- obj = scene.objects.active
-
- # Use a fixed value for now, eventually make this user adjustable
- total = 10
-
- # Add 'total' objects into the scene
- for i in range(total):
- obj_new = obj.copy()
- scene.objects.link(obj_new)
-
- # Now place the object in between the cursor
- # and the active object based on 'i'
- factor = i
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list