Merged changes in the trunk up to revision 44797.

Conflicts resolved:
doc/python_api/sphinx_doc_gen.py
source/blender/makesdna/DNA_mesh_types.h
source/blender/makesrna/intern/rna_action.c
source/blender/makesrna/intern/rna_ID.c
source/blender/makesrna/intern/rna_mesh.c

4 files changed, 463 insertions, 353 deletions

diff --git a/doc/python_api/rst/bge.types.rst b/doc/python_api/rst/bge.types.rst
index 735ad037175..3c15362a4ec 100644
--- a/doc/python_api/rst/bge.types.rst
+++ b/doc/python_api/rst/bge.types.rst
@@ -4518,10 +4518,16 @@ Game Types (bge.types)
 
    .. data:: KX_ACT_ARMATURE_SETWEIGHT
 
-      Change weight of (only for IK constraint).
+      Change weight of constraint (IK only).
 
       :value: 4
 
+   .. data:: KX_ACT_ARMATURE_SETINFLUENCE
+
+      Change influence of constraint.
+
+      :value: 5
+
    .. attribute:: type
 
       The type of action that the actuator executes when it is active.
@@ -4566,6 +4572,12 @@ Game Types (bge.types)
       
          A weight of 0 disables a constraint while still updating constraint runtime values (see :class:`BL_ArmatureConstraint`)
 
+   .. attribute:: influence
+
+      The influence this actuator will set on the constraint it controls.
+
+      :type: float.
+
 .. class:: KX_ArmatureSensor(SCA_ISensor)
 
    Armature sensor detect conditions on armatures.
diff --git a/doc/python_api/rst/info_best_practice.rst b/doc/python_api/rst/info_best_practice.rst
index d191bb608e8..1f0f81f7d14 100644
--- a/doc/python_api/rst/info_best_practice.rst
+++ b/doc/python_api/rst/info_best_practice.rst
@@ -264,7 +264,7 @@ if your unsure whether the text is upper or lower case use lower or upper string
 Use try/except Sparingly
 ------------------------
 
-The **try** statement useful to save time writing error checking code.
+The **try** statement is useful to save time writing error checking code.
 
 However **try** is significantly slower then an **if** since an exception has to be set each time, so avoid using **try** in areas of your code that execute in a loop and runs many times.
 
diff --git a/doc/python_api/rst/info_tips_and_tricks.rst b/doc/python_api/rst/info_tips_and_tricks.rst
index 0b9404906e2..521031f5e61 100644
--- a/doc/python_api/rst/info_tips_and_tricks.rst
+++ b/doc/python_api/rst/info_tips_and_tricks.rst
@@ -82,7 +82,7 @@ You might want to reference a script relative to the blend file.
    import bpy
    import os
 
-   filename = os.path.join(os.path.basename(bpy.data.filepath), "myscript.py")
+   filename = os.path.join(os.path.dirname(bpy.data.filepath), "myscript.py")
    exec(compile(open(filename).read(), filename, 'exec'))
 
 
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py
index 2b07b0c3611..b9444f35e12 100644
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@@ -14,30 +14,33 @@
  # along with this program; if not, write to the Free Software Foundation,
  # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  #
- # Contributor(s): Campbell Barton
+ # Contributor(s): Campbell Barton, Luca Bonavita
  #
  # #**** END GPL LICENSE BLOCK #****
 
 # <pep8 compliant>
 
-script_help_msg = """
+SCRIPT_HELP_MSG = """
 
 API dump in RST files
 ---------------------
   Run this script from blenders root path once you have compiled blender
 
-    ./blender.bin --background -noaudio --python doc/python_api/sphinx_doc_gen.py
+    ./blender.bin -b -noaudio -P doc/python_api/sphinx_doc_gen.py
 
   This will generate python files in doc/python_api/sphinx-in/
   providing ./blender.bin is or links to the blender executable
 
-  To choose sphinx-in directory use the -o option, putting the path  after '--'.
-  Example:
-  ./cmake/bin/blender -b -P ./blender/doc/python_api/sphinx_doc_gen.py -- -o ./python_api
+  To choose sphinx-in directory:
+    ./blender.bin -b -P doc/python_api/sphinx_doc_gen.py -- -o ../python_api
+
+  For quick builds:
+    ./blender.bin -b -P doc/python_api/sphinx_doc_gen.py -- -q
 
 Sphinx: HTML generation
 -----------------------
-  Generate html docs by running...
+  After you have built doc/python_api/sphinx-in (see above),
+  generate html docs by running:
 
     cd doc/python_api
     sphinx-build sphinx-in sphinx-out
@@ -46,19 +49,20 @@ Sphinx: HTML generation
 
 Sphinx: PDF generation
 ----------------------
-  After you have built doc/python_api/sphinx-in (see above), run:
+  After you have built doc/python_api/sphinx-in (see above),
+  generate the pdf doc by running:
 
     sphinx-build -b latex doc/python_api/sphinx-in doc/python_api/sphinx-out
     cd doc/python_api/sphinx-out
     make
-    
+
 """
 
 try:
     import bpy  # blender module
 except:
-    print("\nError, this script must run from inside blender")
-    print(script_help_msg)
+    print("\nERROR: this script must run from inside Blender")
+    print(SCRIPT_HELP_MSG)
     import sys
     sys.exit()
 
@@ -73,64 +77,160 @@ import shutil
 from platform import platform
 PLATFORM = platform().split('-')[0].lower()    # 'linux', 'darwin', 'windows'
 
-# this script dir
-SCRIPT_DIR = os.path.dirname(__file__)
+SCRIPT_DIR = os.path.abspath(os.path.dirname(__file__))
 
-# examples
-EXAMPLES_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "examples"))
-EXAMPLE_SET = set()
-EXAMPLE_SET_USED = set()
 
-#rst files dir
-RST_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "rst"))
+def handle_args():
+    '''
+    Parse the args passed to Blender after "--", ignored by Blender
+    '''
+    import argparse
+
+    # When --help is given, print the usage text
+    parser = argparse.ArgumentParser(
+        formatter_class=argparse.RawTextHelpFormatter,
+        usage=SCRIPT_HELP_MSG
+    )
+
+    # optional arguments
+    parser.add_argument("-o", "--output",
+                        dest="output_dir",
+                        type=str,
+                        default=SCRIPT_DIR,
+                        help="Path of the API docs (default=<script dir>)",
+                        required=False)
+
+    parser.add_argument("-B", "--sphinx-build",
+                        dest="sphinx_build",
+                        default=False,
+                        action='store_true',
+                        help="Run sphinx-build SPHINX_IN SPHINX_OUT (default=False)",
+                        required=False)
+
+    parser.add_argument("-N", "--sphinx-named-output",
+                        dest="sphinx_named_output",
+                        default=False,
+                        action='store_true',
+                        help="Add the theme name to the html dir name (default=False)",
+                        required=False)
+
+    parser.add_argument("-T", "--sphinx-theme",
+                        dest="sphinx_theme",
+                        type=str,
+                        default='default',
+                        help=
+                        # see SPHINX_THEMES below
+                        "Sphinx theme (default='default')\n"
+                        "Available themes\n"
+                        "----------------\n"
+                        "(Blender Foundation) blender-org\n"    # naiad
+                        "(Sphinx) agogo, basic, epub, haiku, nature, "
+                        "scrolls, sphinxdoc, traditional\n",
+#                        choices=['naiad', 'blender-org'] +      # bf
+#                                ['agogo', 'basic', 'epub',
+#                                 'haiku', 'nature', 'scrolls',
+#                                 'sphinxdoc', 'traditional'],   # sphinx
+                        required=False)
+
+    parser.add_argument("-f", "--fullrebuild",
+                        dest="full_rebuild",
+                        default=False,
+                        action='store_true',
+                        help="Rewrite all rst files in sphinx-in/ (default=False)",
+                        required=False)
+
+    parser.add_argument("-t", "--testdump",
+                        dest="test_dump",
+                        default=False,
+                        action='store_true',
+                        help="Dumps a small part of the API (default=False)",
+                        required=False)
+
+    parser.add_argument("-b", "--bpy",
+                        dest="bpy",
+                        default=False,
+                        action='store_true',
+                        help="Write the rst file of the bpy module (default=False)",
+                        required=False)
+
+    # parse only the args passed after '--'
+    argv = []
+    if "--" in sys.argv:
+        argv = sys.argv[sys.argv.index("--") + 1:]  # get all args after "--"
+
+    return parser.parse_args(argv)
+
+
+ARGS = handle_args()
+
+# ----------------------------------BPY-----------------------------------------
 
-# Switch for quick testing
-if 1:
+"""
+# for quick rebuilds
+rm -rf /b/doc/python_api/sphinx-* && \
+./blender.bin --background -noaudio --factory-startup --python  doc/python_api/sphinx_doc_gen.py && \
+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:
     # full build
+    FILTER_BPY_OPS = None
+    FILTER_BPY_TYPES = None
     EXCLUDE_INFO_DOCS = False
     EXCLUDE_MODULES = ()
-    FILTER_BPY_TYPES = None
-    FILTER_BPY_OPS = None
 
 else:
+    FILTER_BPY_OPS = ("import.scene", )  # allow
+    FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID")  # allow
     EXCLUDE_INFO_DOCS = True
-    # for testing so doc-builds dont take so long.
     EXCLUDE_MODULES = (
-        "bpy.context",
+        "aud",
+        "bge",
+        "bge.constraints",
+        "bge.events",
+        "bge.logic",
+        "bge.render",
+        "bge.texture",
+        "bge.types",
+        "bgl",
+        "blf",
+        #"bmesh",
+        #"bmesh.types",
+        #"bmesh.utils",
         "bpy.app",
         "bpy.app.handlers",
-        "bpy.path",
+        "bpy.context",
         "bpy.data",
+        "bpy.ops",  # supports filtering
+        "bpy.path",
         "bpy.props",
-        "bpy.utils",
-        "bpy.context",
         "bpy.types",  # supports filtering
-        "bpy.ops",  # supports filtering
+        "bpy.utils",
         "bpy_extras",
-        "bge",
-        "aud",
-        "bgl",
-        "blf",
         "gpu",
         "mathutils",
         "mathutils.geometry",
         "mathutils.noise",
-        #"bmesh",
-        #"bmesh.types",
-        #"bmesh.utils",
         "Freestyle",
     )
 
-    FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID")  # allow
-    FILTER_BPY_OPS = ("import.scene", )  # allow
+try:
+    __import__("aud")
+except ImportError:
+    print("Warning: Built without 'aud' module, docs incomplete...")
+    EXCLUDE_MODULES = EXCLUDE_MODULES + ("aud", )
 
-    # for quick rebuilds
-    """
-rm -rf /b/doc/python_api/sphinx-* && \
-./blender.bin --background -noaudio --factory-startup --python  doc/python_api/sphinx_doc_gen.py && \
-sphinx-build doc/python_api/sphinx-in doc/python_api/sphinx-out
+# examples
+EXAMPLES_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "examples"))
+EXAMPLE_SET = set()
+for f in os.listdir(EXAMPLES_DIR):
+    if f.endswith(".py"):
+        EXAMPLE_SET.add(os.path.splitext(f)[0])
+EXAMPLE_SET_USED = set()
 
-    """
+#rst files dir
+RST_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "rst"))
 
 # extra info, not api reference docs
 # stored in ./rst/info_*
@@ -138,26 +238,68 @@ INFO_DOCS = (
     ("info_quickstart.rst", "Blender/Python Quickstart: new to blender/scripting and want to get your feet wet?"),
     ("info_overview.rst", "Blender/Python API Overview: a more complete explanation of python integration"),
     ("info_best_practice.rst", "Best Practice: Conventions to follow for writing good scripts"),
-    ("info_tips_and_tricks.rst", "Tips and Tricks: Hints to help you while writeing scripts for blender"),
+    ("info_tips_and_tricks.rst", "Tips and Tricks: Hints to help you while writing scripts for blender"),
     ("info_gotcha.rst", "Gotcha's: some of the problems you may come up against when writing scripts"),
     )
 
 # only support for properties atm.
 RNA_BLACKLIST = {
-    # messes up PDF!, really a bug but for now just workaround.
-    "UserPreferencesSystem": {"language", },
+    # XXX messes up PDF!, really a bug but for now just workaround.
+    "UserPreferencesSystem": {"language", }
     }
 
 
-# -----------------------------------------------------------------------------
+# -------------------------------SPHINX-----------------------------------------
+
+SPHINX_THEMES = {'bf': ['blender-org'], # , 'naiad',
+                 'sphinx': ['agogo',
+                            'basic',
+                            'default',
+                            'epub',
+                            'haiku',
+                            'nature',
+                            'scrolls',
+                            'sphinxdoc',
+                            'traditional']}
+
+available_themes = SPHINX_THEMES['bf'] + SPHINX_THEMES['sphinx']
+if ARGS.sphinx_theme not in available_themes:
+    print ("Please choose a theme among: %s" % ', '.join(available_themes))
+    sys.exit()
+
+SPHINX_IN = os.path.join(ARGS.output_dir, "sphinx-in")
+SPHINX_IN_TMP = SPHINX_IN + "-tmp"
+SPHINX_OUT = os.path.join(ARGS.output_dir, "sphinx-out")
+if ARGS.sphinx_named_output:
+    SPHINX_OUT += "_%s" % ARGS.sphinx_theme
+
+if ARGS.sphinx_theme in SPHINX_THEMES['bf']:
+    SPHINX_THEME_DIR = os.path.join(ARGS.output_dir, ARGS.sphinx_theme)
+    SPHINX_THEME_SVN_DIR = os.path.join(SCRIPT_DIR, ARGS.sphinx_theme)
+
+# ------------------------------------------------------------------------------
+
 # configure compile time options
 
-try:
-    __import__("aud")
-except ImportError:
-    print("Warning: Built without 'aud' module, docs incomplete...")
-    EXCLUDE_MODULES = EXCLUDE_MODULES + ("aud", )
+# -------------------------------BLENDER----------------------------------------
+
+'''
+blender version
+'''
+version_strings = [str(v) for v in bpy.app.version]
+
+BLENDER_VERSION_DOTS = ".".join(version_strings)    # '2.62.1'
+if bpy.app.build_revision != b"Unknown":
+    # converting bytes to strings, due to #30154
+    BLENDER_VERSION_DOTS += " r" + str(bpy.app.build_revision, 'utf_8')    # '2.62.1 r44584'
 
+BLENDER_VERSION_PDF = "_".join(version_strings)    # '2_62_1'
+if bpy.app.version_cycle == "release":
+    BLENDER_VERSION_PDF = "%s%s_release" % ("_".join(version_strings[:2]),
+                                            bpy.app.version_char)   # '2_62_release'
+
+
+# --------------------------------API DUMP--------------------------------------
 
 # lame, python wont give some access
 ClassMethodDescriptorType = type(dict.__dict__['fromkeys'])
@@ -168,7 +310,6 @@ from types import MemberDescriptorType
 
 _BPY_STRUCT_FAKE = "bpy_struct"
 _BPY_PROP_COLLECTION_FAKE = "bpy_prop_collection"
-_BPY_FULL_REBUILD = False
 
 if _BPY_PROP_COLLECTION_FAKE:
     _BPY_PROP_COLLECTION_ID = ":class:`%s`" % _BPY_PROP_COLLECTION_FAKE
@@ -185,10 +326,13 @@ def undocumented_message(module_name, type_name, identifier):
         preloadtitle = '%s.%s' % (module_name, identifier)
     else:
         preloadtitle = '%s.%s.%s' % (module_name, type_name, identifier)
-    message = "Undocumented (`contribute "\
-        "<http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute"\
-        "?action=edit&section=new&preload=Dev:2.5/Py/API/Documentation/Contribute/Howto-message"\
-        "&preloadtitle=%s>`_)\n\n" % preloadtitle
+    message =   "Undocumented (`contribute "\
+                "<http://wiki.blender.org/index.php/"\
+                "Dev:2.5/Py/API/Generating_API_Reference/Contribute/Howto-message"\
+                "?action=edit"\
+                "&section=new"\
+                "&preload=Dev:2.5/Py/API/Documentation/Contribute/Howto-message"\
+                "&preloadtitle=%s>`_)\n\n" % preloadtitle
     return message
 
 
@@ -402,10 +546,10 @@ def pyprop2sphinx(ident, fw, identifier, py_prop):
         fw(ident + "   (readonly)\n\n")
 
 
-def pymodule2sphinx(BASEPATH, module_name, module, title):
+def pymodule2sphinx(basepath, module_name, module, title):
     import types
     attribute_set = set()
-    filepath = os.path.join(BASEPATH, module_name + ".rst")
+    filepath = os.path.join(basepath, module_name + ".rst")
 
     module_all = getattr(module, "__all__", None)
     module_dir = sorted(dir(module))
@@ -453,7 +597,7 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
                 submod_name_full = "%s.%s" % (module_name, submod_name)
                 fw("   %s.rst\n\n" % submod_name_full)
 
-                pymodule2sphinx(BASEPATH, submod_name_full, submod, "%s submodule" % module_name)
+                pymodule2sphinx(basepath, submod_name_full, submod, "%s submodule" % module_name)
         del submod_ls
     # done writing submodules!
 
@@ -596,10 +740,10 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
     file.close()
 
 
-def pycontext2sphinx(BASEPATH):
+def pycontext2sphinx(basepath):
     # Only use once. very irregular
 
-    filepath = os.path.join(BASEPATH, "bpy.context.rst")
+    filepath = os.path.join(basepath, "bpy.context.rst")
     file = open(filepath, "w", encoding="utf-8")
     fw = file.write
     fw("Context Access (bpy.context)\n")
@@ -738,7 +882,7 @@ def pyrna_enum2sphinx(prop, use_empty_descriptions=False):
         return ""
 
 
-def pyrna2sphinx(BASEPATH):
+def pyrna2sphinx(basepath):
     """ bpy.types and bpy.ops
     """
     structs, funcs, ops, props = rna_info.BuildRNAInfo()
@@ -790,7 +934,7 @@ def pyrna2sphinx(BASEPATH):
         #if not struct.identifier == "Object":
         #    return
 
-        filepath = os.path.join(BASEPATH, "bpy.types.%s.rst" % struct.identifier)
+        filepath = os.path.join(basepath, "bpy.types.%s.rst" % struct.identifier)
         file = open(filepath, "w", encoding="utf-8")
         fw = file.write
 
@@ -1013,7 +1157,7 @@ def pyrna2sphinx(BASEPATH):
             write_struct(struct)
 
         def fake_bpy_type(class_value, class_name, descr_str, use_subclasses=True):
-            filepath = os.path.join(BASEPATH, "bpy.types.%s.rst" % class_name)
+            filepath = os.path.join(basepath, "bpy.types.%s.rst" % class_name)
             file = open(filepath, "w", encoding="utf-8")
             fw = file.write
 
@@ -1064,7 +1208,7 @@ def pyrna2sphinx(BASEPATH):
         del op
 
         for op_module_name, ops_mod in op_modules.items():
-            filepath = os.path.join(BASEPATH, "bpy.ops.%s.rst" % op_module_name)
+            filepath = os.path.join(basepath, "bpy.ops.%s.rst" % op_module_name)
             file = open(filepath, "w", encoding="utf-8")
             fw = file.write
 
@@ -1102,7 +1246,10 @@ def pyrna2sphinx(BASEPATH):
                     else:
                         url_base = API_BASEURL
 
-                    fw("   :file: `%s <%s/%s>`_:%d\n\n" % (location[0], url_base, location[0], location[1]))
+                    fw("   :file: `%s <%s/%s>`_:%d\n\n" % (location[0],
+                                                           url_base,
+                                                           location[0],
+                                                           location[1]))
 
             file.close()
 
@@ -1110,53 +1257,43 @@ def pyrna2sphinx(BASEPATH):
         write_ops()
 
 
-def rna2sphinx(BASEPATH):
-
-    try:
-        os.mkdir(BASEPATH)
-    except:
-        pass
-
-    # conf.py - empty for now
-    filepath = os.path.join(BASEPATH, "conf.py")
+def write_sphinx_conf_py(basepath):
+    '''
+    Write sphinx's conf.py
+    '''
+    filepath = os.path.join(basepath, "conf.py")
     file = open(filepath, "w", encoding="utf-8")
     fw = file.write
 
-    version_string = ".".join(str(v) for v in bpy.app.version)
-    if bpy.app.build_revision != "Unknown":
-        version_string = version_string + " r" + bpy.app.build_revision
-
-    version_string_fp = "_".join(str(v) for v in bpy.app.version)
-
-    if bpy.app.version_cycle == "release":
-        version_string_pdf = "%s%s_release" % ("_".join(str(v) for v in bpy.app.version[:2]), bpy.app.version_char)
-    else:
-        version_string_pdf = version_string_fp
-
     fw("project = 'Blender'\n")
     # fw("master_doc = 'index'\n")
     fw("copyright = u'Blender Foundation'\n")
-    fw("version = '%s - API'\n" % version_string)
-    fw("release = '%s - API'\n" % version_string)
+    fw("version = '%s - API'\n" % BLENDER_VERSION_DOTS)
+    fw("release = '%s - API'\n" % BLENDER_VERSION_DOTS)
 
-    # until we get a theme for 'Naiad'
-    if 0:
-        fw("html_theme = 'blender-org'\n")
-        fw("html_theme_path = ['../']\n")
+    if ARGS.sphinx_theme != 'default':
+        fw("html_theme = '%s'\n" % ARGS.sphinx_theme)
 
+    if ARGS.sphinx_theme in SPHINX_THEMES['bf']:
+        fw("html_theme_path = ['../']\n")
         # copied with the theme, exclude else we get an error [#28873]
-        fw("html_favicon = 'favicon.ico'\n")
+        fw("html_favicon = 'favicon.ico'\n")    # in <theme>/static/
 
-    # not helpful since the source us generated, adds to upload size.
+    # not helpful since the source is generated, adds to upload size.
     fw("html_copy_source = False\n")
     fw("\n")
+
     # needed for latex, pdf gen
     fw("latex_documents = [ ('contents', 'contents.tex', 'Blender Index', 'Blender Foundation', 'manual'), ]\n")
     fw("latex_paper_size = 'a4paper'\n")
     file.close()
 
-    # main page needed for sphinx (index.html)
-    filepath = os.path.join(BASEPATH, "contents.rst")
+
+def write_rst_contents(basepath):
+    '''
+    Write the rst file of the main page, needed for sphinx (index.html)
+    '''
+    filepath = os.path.join(basepath, "contents.rst")
     file = open(filepath, "w", encoding="utf-8")
     fw = file.write
 
@@ -1164,11 +1301,11 @@ def rna2sphinx(BASEPATH):
     fw(" Blender Documentation contents\n")
     fw("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n")
     fw("\n")
-    fw("Welcome, this document is an API reference for Blender %s. built %s.\n" % (version_string, bpy.app.build_date))
+    fw("Welcome, this document is an API reference for Blender %s. built %s.\n" % (BLENDER_VERSION_DOTS, str(bpy.app.build_date, 'utf_8')))
     fw("\n")
 
-    # fw("`A PDF version of this document is also available <blender_python_reference_%s.pdf>`_\n" % version_string_pdf)
-    fw("`A compressed ZIP file of this site is available <blender_python_reference_%s.zip>`_\n" % version_string_pdf)
+    # fw("`A PDF version of this document is also available <blender_python_reference_%s.pdf>`_\n" % BLENDER_VERSION_PDF)
+    fw("`A compressed ZIP file of this site is available <blender_python_reference_%s.zip>`_\n" % BLENDER_VERSION_PDF)
 
     fw("\n")
 
@@ -1190,28 +1327,25 @@ def rna2sphinx(BASEPATH):
     fw("\n")
     fw(".. toctree::\n")
     fw("   :maxdepth: 1\n\n")
-    if "bpy.context" not in EXCLUDE_MODULES:
-        fw("   bpy.context.rst\n\n")  # note: not actually a module
-    if "bpy.data" not in EXCLUDE_MODULES:
-        fw("   bpy.data.rst\n\n")  # note: not actually a module
-    if "bpy.ops" not in EXCLUDE_MODULES:
-        fw("   bpy.ops.rst\n\n")
-    if "bpy.types" not in EXCLUDE_MODULES:
-        fw("   bpy.types.rst\n\n")
-
-    # py modules
-    if "bpy.utils" not in EXCLUDE_MODULES:
-        fw("   bpy.utils.rst\n\n")
-    if "bpy.path" not in EXCLUDE_MODULES:
-        fw("   bpy.path.rst\n\n")
-    if "bpy.app" not in EXCLUDE_MODULES:
-        fw("   bpy.app.rst\n\n")
-    if "bpy.app.handlers" not in EXCLUDE_MODULES:
-        fw("   bpy.app.handlers.rst\n\n")
-
-    # C modules
-    if "bpy.props" not in EXCLUDE_MODULES:
-        fw("   bpy.props.rst\n\n")
+
+    app_modules = [
+        "bpy.context",  # note: not actually a module
+        "bpy.data",     # note: not actually a module
+        "bpy.ops",
+        "bpy.types",
+
+        # py modules
+        "bpy.utils",
+        "bpy.path",
+        "bpy.app",
+        "bpy.app.handlers",
+
+        # C modules
+        "bpy.props"
+    ]
+    for mod in app_modules:
+        if mod not in EXCLUDE_MODULES:
+            fw("   %s\n\n" % mod)
 
     fw("==================\n")
     fw("Standalone Modules\n")
@@ -1220,33 +1354,17 @@ def rna2sphinx(BASEPATH):
     fw(".. toctree::\n")
     fw("   :maxdepth: 1\n\n")
 
-    # mathutils
-    if "mathutils" not in EXCLUDE_MODULES:
-        fw("   mathutils.rst\n\n")
-    if "mathutils.geometry" not in EXCLUDE_MODULES:
-        fw("   mathutils.geometry.rst\n\n")
-    if "mathutils.noise" not in EXCLUDE_MODULES:
-        fw("   mathutils.noise.rst\n\n")
-    # misc
-    if "Freestyle" not in EXCLUDE_MODULES:
-        fw("   Freestyle.rst\n\n")
-    if "bgl" not in EXCLUDE_MODULES:
-        fw("   bgl.rst\n\n")
-    if "blf" not in EXCLUDE_MODULES:
-        fw("   blf.rst\n\n")
-    if "gpu" not in EXCLUDE_MODULES:
-        fw("   gpu.rst\n\n")
-    if "aud" not in EXCLUDE_MODULES:
-        fw("   aud.rst\n\n")
-    if "bpy_extras" not in EXCLUDE_MODULES:
-        fw("   bpy_extras.rst\n\n")
-    # bmesh
-    if "bmesh" not in EXCLUDE_MODULES:
-        fw("   bmesh.rst\n\n")
-    if "bmesh.types" not in EXCLUDE_MODULES:
-        fw("   bmesh.types.rst\n\n")
-    if "bmesh.utils" not in EXCLUDE_MODULES:
-        fw("   bmesh.utils.rst\n\n")
+    standalone_modules = [
+        # mathutils
+        "mathutils", "mathutils.geometry", "mathutils.noise",
+        # misc
+        "Freestyle", "bgl", "blf", "gpu", "aud", "bpy_extras",
+        # bmesh
+        "bmesh", "bmesh.types", "bmesh.utils"
+    ]
+    for mod in standalone_modules:
+        if mod not in EXCLUDE_MODULES:
+            fw("   %s\n\n" % mod)
 
     # game engine
     if "bge" not in EXCLUDE_MODULES:
@@ -1289,21 +1407,32 @@ def rna2sphinx(BASEPATH):
 
     file.close()
 
-    # internal modules
-    if "bpy.ops" not in EXCLUDE_MODULES:
-        filepath = os.path.join(BASEPATH, "bpy.ops.rst")
+
+def write_rst_bpy(basepath):
+    '''
+    Write rst file of bpy module (disabled by default)
+    '''
+    if ARGS.bpy:
+        filepath = os.path.join(basepath, "bpy.rst")
         file = open(filepath, "w", encoding="utf-8")
         fw = file.write
-        fw("Operators (bpy.ops)\n")
-        fw("===================\n\n")
-        write_example_ref("", fw, "bpy.ops")
-        fw(".. toctree::\n")
-        fw("   :glob:\n\n")
-        fw("   bpy.ops.*\n\n")
+
+        fw("\n")
+
+        title = ":mod:`bpy` --- Blender Python Module"
+
+        write_title(fw, title, "=")
+
+        fw(".. module:: bpy.types\n\n")
         file.close()
 
+
+def write_rst_types_index(basepath):
+    '''
+    Write the rst file of bpy.types module (index)
+    '''
     if "bpy.types" not in EXCLUDE_MODULES:
-        filepath = os.path.join(BASEPATH, "bpy.types.rst")
+        filepath = os.path.join(basepath, "bpy.types.rst")
         file = open(filepath, "w", encoding="utf-8")
         fw = file.write
         fw("Types (bpy.types)\n")
@@ -1313,10 +1442,32 @@ def rna2sphinx(BASEPATH):
         fw("   bpy.types.*\n\n")
         file.close()
 
+
+def write_rst_ops_index(basepath):
+    '''
+    Write the rst file of bpy.ops module (index)
+    '''
+    if "bpy.ops" not in EXCLUDE_MODULES:
+        filepath = os.path.join(basepath, "bpy.ops.rst")
+        file = open(filepath, "w", encoding="utf-8")
+        fw = file.write
+        fw("Operators (bpy.ops)\n")
+        fw("===================\n\n")
+        write_example_ref("", fw, "bpy.ops")
+        fw(".. toctree::\n")
+        fw("   :glob:\n\n")
+        fw("   bpy.ops.*\n\n")
+        file.close()
+
+
+def write_rst_data(basepath):
+    '''
+    Write the rst file of bpy.data module
+    '''
     if "bpy.data" not in EXCLUDE_MODULES:
         # not actually a module, only write this file so we
         # can reference in the TOC
-        filepath = os.path.join(BASEPATH, "bpy.data.rst")
+        filepath = os.path.join(basepath, "bpy.data.rst")
         file = open(filepath, "w", encoding="utf-8")
         fw = file.write
         fw("Data Access (bpy.data)\n")
@@ -1334,220 +1485,152 @@ def rna2sphinx(BASEPATH):
         fw(".. literalinclude:: ../examples/bpy.data.py\n")
         file.close()
 
-    EXAMPLE_SET_USED.add("bpy.data")
+        EXAMPLE_SET_USED.add("bpy.data")
 
-    module = None
 
-    if "bpy.context" not in EXCLUDE_MODULES:
-        # one of a kind, context doc (uses ctypes to extract info!)
-        # doesn't work on mac
-        if PLATFORM != "darwin":
-            pycontext2sphinx(BASEPATH)
-
-    # python modules
-    if "bpy.utils" not in EXCLUDE_MODULES:
-        from bpy import utils as module
-        pymodule2sphinx(BASEPATH, "bpy.utils", module, "Utilities")
-
-    if "bpy.path" not in EXCLUDE_MODULES:
-        from bpy import path as module
-        pymodule2sphinx(BASEPATH, "bpy.path", module, "Path Utilities")
-
-    if "bpy_extras" not in EXCLUDE_MODULES:
-        import bpy_extras as module
-        pymodule2sphinx(BASEPATH, "bpy_extras", module, "Extra Utilities")
-
-    # C modules
-    if "bpy.app" not in EXCLUDE_MODULES:
-        from bpy import app as module
-        pymodule2sphinx(BASEPATH, "bpy.app", module, "Application Data")
-
-    if "bpy.app.handlers" not in EXCLUDE_MODULES:
-        from bpy.app import handlers as module
-        pymodule2sphinx(BASEPATH, "bpy.app.handlers", module, "Application Handlers")
-
-    if "bpy.props" not in EXCLUDE_MODULES:
-        from bpy import props as module
-        pymodule2sphinx(BASEPATH, "bpy.props", module, "Property Definitions")
-
-    if "mathutils" not in EXCLUDE_MODULES:
-        import mathutils as module
-        pymodule2sphinx(BASEPATH, "mathutils", module, "Math Types & Utilities")
-
-    if "mathutils.geometry" not in EXCLUDE_MODULES:
-        import mathutils.geometry as module
-        pymodule2sphinx(BASEPATH, "mathutils.geometry", module, "Geometry Utilities")
-
-    if "mathutils.noise" not in EXCLUDE_MODULES:
-        import mathutils.noise as module
-        pymodule2sphinx(BASEPATH, "mathutils.noise", module, "Noise Utilities")
-
-    if "bmesh" not in EXCLUDE_MODULES:
-        import bmesh as module
-        pymodule2sphinx(BASEPATH, "bmesh", module, "BMesh Module")
-
-    if "bmesh.types" not in EXCLUDE_MODULES:
-        import bmesh.types as module
-        pymodule2sphinx(BASEPATH, "bmesh.types", module, "BMesh Types")
-
-    if "bmesh.utils" not in EXCLUDE_MODULES:
-        import bmesh.utils as module
-        pymodule2sphinx(BASEPATH, "bmesh.utils", module, "BMesh Utilities")
-
-    if "Freestyle" not in EXCLUDE_MODULES:
-        import Freestyle as module
-        pymodule2sphinx(BASEPATH, "Freestyle", module, "Freestyle Data Types & Operators")
-
-    if "blf" not in EXCLUDE_MODULES:
-        import blf as module
-        pymodule2sphinx(BASEPATH, "blf", module, "Font Drawing")
-
-    if "bgl" not in EXCLUDE_MODULES:
-        #import bgl as module
-        #pymodule2sphinx(BASEPATH, "bgl", module, "Blender OpenGl wrapper")
-        #del module
-        shutil.copy2(os.path.join(RST_DIR, "bgl.rst"), BASEPATH)
-
-    if "gpu" not in EXCLUDE_MODULES:
-        #import gpu as module
-        #pymodule2sphinx(BASEPATH, "gpu", module, "GPU Shader Module")
-        #del module
-        shutil.copy2(os.path.join(RST_DIR, "gpu.rst"), BASEPATH)
-
-    if "aud" not in EXCLUDE_MODULES:
-        import aud as module
-        pymodule2sphinx(BASEPATH, "aud", module, "Audio System")
-    del module
-
-    ## game engine
-
-    # copy2 keeps time/date stamps
-    if "bge" not in EXCLUDE_MODULES:
-        shutil.copy2(os.path.join(RST_DIR, "bge.types.rst"), BASEPATH)
-        shutil.copy2(os.path.join(RST_DIR, "bge.logic.rst"), BASEPATH)
-        shutil.copy2(os.path.join(RST_DIR, "bge.render.rst"), BASEPATH)
-        shutil.copy2(os.path.join(RST_DIR, "bge.texture.rst"), BASEPATH)
-        shutil.copy2(os.path.join(RST_DIR, "bge.events.rst"), BASEPATH)
-        shutil.copy2(os.path.join(RST_DIR, "bge.constraints.rst"), BASEPATH)
+def write_rst_importable_modules(basepath):
+    '''
+    Write the rst files of importable modules
+    '''
+    importable_modules = {
+        # python_modules
+        "bpy.path"          : "Path Utilities",
+        "bpy.utils"         : "Utilities",
+        "bpy_extras"        : "Extra Utilities",
+
+        # C_modules
+        "aud"               : "Audio System",
+        "blf"               : "Font Drawing",
+        "bmesh"             : "BMesh Module",
+        "bmesh.types"       : "BMesh Types",
+        "bmesh.utils"       : "BMesh Utilities",
+        "bpy.app"           : "Application Data",
+        "bpy.app.handlers"  : "Application Handlers",
+        "bpy.props"         : "Property Definitions",
+        "mathutils"         : "Math Types & Utilities",
+        "mathutils.geometry": "Geometry Utilities",
+        "mathutils.noise"   : "Noise Utilities",
+        "Freestyle"         : "Freestyle Data Types & Operators",
+    }
+    for mod_name, mod_descr in importable_modules.items():
+        if mod_name not in EXCLUDE_MODULES:
+            module = __import__(mod_name,
+                                fromlist=[mod_name.rsplit(".", 1)[-1]])
+            pymodule2sphinx(basepath, mod_name, module, mod_descr)
 
-    shutil.copy2(os.path.join(RST_DIR, "change_log.rst"), BASEPATH)
 
+def copy_handwritten_rsts(basepath):
+
+    # info docs
     if not EXCLUDE_INFO_DOCS:
         for info, info_desc in INFO_DOCS:
-            shutil.copy2(os.path.join(RST_DIR, info), BASEPATH)
+            shutil.copy2(os.path.join(RST_DIR, info), basepath)
+
+    # TODO put this docs in blender's code and use import as per modules above
+    handwritten_modules = [
+        "bge.types",
+        "bge.logic",
+        "bge.render",
+        "bge.texture",
+        "bge.events",
+        "bge.constraints",
+        "bgl",  # "Blender OpenGl wrapper"
+        "gpu",  # "GPU Shader Module"
+    ]
+    for mod_name in handwritten_modules:
+        if mod_name not in EXCLUDE_MODULES:
+            # copy2 keeps time/date stamps
+            shutil.copy2(os.path.join(RST_DIR, "%s.rst" % mod_name), basepath)
+
+    # changelog
+    shutil.copy2(os.path.join(RST_DIR, "change_log.rst"), basepath)
+
+
+def rna2sphinx(basepath):
 
-    if 0:
-        filepath = os.path.join(BASEPATH, "bpy.rst")
-        file = open(filepath, "w", encoding="utf-8")
-        fw = file.write
-
-        fw("\n")
+    try:
+        os.mkdir(basepath)
+    except:
+        pass
 
-        title = ":mod:`bpy` --- Blender Python Module"
+    # sphinx setup
+    write_sphinx_conf_py(basepath)
 
-        write_title(fw, title, "=")
+    # main page
+    write_rst_contents(basepath)
 
-        fw(".. module:: bpy.types\n\n")
-        file.close()
+    # context
+    if "bpy.context" not in EXCLUDE_MODULES:
+        # one of a kind, context doc (uses ctypes to extract info!)
+        # doesn't work on mac
+        if PLATFORM != "darwin":
+            pycontext2sphinx(basepath)
 
-    # bpy.types and bpy.ops
-    pyrna2sphinx(BASEPATH)
+    # internal modules
+    write_rst_bpy(basepath)                 # bpy, disabled by default
+    write_rst_types_index(basepath)         # bpy.types
+    write_rst_ops_index(basepath)           # bpy.ops
+    pyrna2sphinx(basepath)                  # bpy.types.* and bpy.ops.*
+    write_rst_data(basepath)                # bpy.data
+    write_rst_importable_modules(basepath)
 
-    file.close()
+    # copy the other rsts
+    copy_handwritten_rsts(basepath)
 
 
-def handle_args():
+def align_sphinx_in_to_sphinx_in_tmp():
     '''
-    get the args passed to blender after "--", all of which are ignored by blender
-    
-    we can give the path of sphinx-in after '--', using for example:
-    ./cmake/bin/blender -b -P ./blender/doc/python_api/sphinx_doc_gen.py -- ./python_api
+    Move changed files from SPHINX_IN_TMP to SPHINX_IN
     '''
-    
-    import argparse  # to parse options for us and print a nice help message
-    
-    # When --help or no args are given, print the usage text
-    parser = argparse.ArgumentParser(
-                                     formatter_class=argparse.RawDescriptionHelpFormatter,
-                                     usage=script_help_msg)
-    
-    # output dir for apidocs 
-    parser.add_argument("-o", "--output",
-                        dest="output_dir",
-                        type=str,
-                        required=False,
-                        help="Path of API docs directory (optional)")
-            
-    argv = []
-    if "--" in sys.argv:
-        argv = sys.argv[sys.argv.index("--") + 1:]  # get all args after "--"
-    
-    return parser.parse_args(argv)
-
-
-def main():
-    
-    args = handle_args()
-    
-    # output dirs
-    if args.output_dir:
-        output_dir = args.output_dir
-        if not os.path.exists(args.output_dir):
-            os.mkdir(args.output_dir)
-    else:
-        output_dir = SCRIPT_DIR
-
-    sphinx_in_dir = os.path.join(output_dir, "sphinx-in")
-    sphinx_out_dir = os.path.join(output_dir, "sphinx-out")
-
-    # only for partial updates
-    sphinx_in_tmp_dir = sphinx_in_dir + "-tmp"
-    if not os.path.exists(sphinx_in_dir):
-        os.mkdir(sphinx_in_dir)
+    import filecmp
 
-    for f in os.listdir(EXAMPLES_DIR):
-        if f.endswith(".py"):
-            EXAMPLE_SET.add(os.path.splitext(f)[0])
-
-    # only for full updates
-    if _BPY_FULL_REBUILD:
-        shutil.rmtree(sphinx_in_dir, True)
-        shutil.rmtree(sphinx_out_dir, True)
-    else:
-        # write here, then move
-        shutil.rmtree(sphinx_in_tmp_dir, True)
+    sphinx_in_files = set(os.listdir(SPHINX_IN))
+    sphinx_in_tmp_files = set(os.listdir(SPHINX_IN_TMP))
 
-    rna2sphinx(sphinx_in_tmp_dir)
+    # remove deprecated files that have been removed
+    for f in sorted(sphinx_in_files):
+        if f not in sphinx_in_tmp_files:
+            print("\tdeprecated: %s" % f)
+            os.remove(os.path.join(SPHINX_IN, f))
 
-    if not _BPY_FULL_REBUILD:
-        import filecmp
+    # freshen with new files.
+    for f in sorted(sphinx_in_tmp_files):
+        f_from = os.path.join(SPHINX_IN_TMP, f)
+        f_to = os.path.join(SPHINX_IN, f)
 
-        # now move changed files from 'sphinx_in_tmp_dir' --> 'sphinx_in_dir'
-        file_list_sphinx_in_dir = set(os.listdir(sphinx_in_dir))
-        file_list_sphinx_in_tmp_dir = set(os.listdir(sphinx_in_tmp_dir))
+        do_copy = True
+        if f in sphinx_in_files:
+            if filecmp.cmp(f_from, f_to):
+                do_copy = False
 
-        # remove deprecated files that have been removed.
-        for f in sorted(file_list_sphinx_in_dir):
-            if f not in file_list_sphinx_in_tmp_dir:
-                print("\tdeprecated: %s" % f)
-                os.remove(os.path.join(sphinx_in_dir, f))
+        if do_copy:
+            print("\tupdating: %s" % f)
+            shutil.copy(f_from, f_to)
 
-        # freshen with new files.
-        for f in sorted(file_list_sphinx_in_tmp_dir):
-            f_from = os.path.join(sphinx_in_tmp_dir, f)
-            f_to = os.path.join(sphinx_in_dir, f)
 
-            do_copy = True
-            if f in file_list_sphinx_in_dir:
-                if filecmp.cmp(f_from, f_to):
-                    do_copy = False
+def main():
 
-            if do_copy:
-                print("\tupdating: %s" % f)
-                shutil.copy(f_from, f_to)
-            '''else:
-                print("\tkeeping: %s" % f) # eh, not that useful'''
+    # dirs preparation
+    for dir_path in [ARGS.output_dir, SPHINX_IN]:
+        if not os.path.exists(dir_path):
+            os.mkdir(dir_path)
+
+    # dump the api in rst files
+    if ARGS.full_rebuild:
+        # only for full updates
+        shutil.rmtree(SPHINX_IN, True)
+        shutil.rmtree(SPHINX_OUT, True)
+        rna2sphinx(SPHINX_IN_TMP)
+        shutil.copytree(SPHINX_IN_TMP,
+                        SPHINX_IN,
+                        copy_function=shutil.copy)
+    else:
+        # write here, then move
+        shutil.rmtree(SPHINX_IN_TMP, True)
+        rna2sphinx(SPHINX_IN_TMP)
+        align_sphinx_in_to_sphinx_in_tmp()
 
+    # report which example files weren't used
     EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED
     if EXAMPLE_SET_UNUSED:
         print("\nUnused examples found in '%s'..." % EXAMPLES_DIR)
@@ -1555,7 +1638,22 @@ def main():
             print("    %s.py" % f)
         print("  %d total\n" % len(EXAMPLE_SET_UNUSED))
 
+    # eventually, copy the theme in the output directory
+    if ARGS.sphinx_theme in SPHINX_THEMES['bf']:
+        if not os.path.exists(SPHINX_THEME_DIR):
+            shutil.copytree(SPHINX_THEME_SVN_DIR,
+                            SPHINX_THEME_DIR,
+                            copy_function=shutil.copy)
+
+    # eventually, build the docs
+    if ARGS.sphinx_build:
+        import subprocess
+        sphinx_build_command = "sphinx-build %s %s" % (SPHINX_IN, SPHINX_OUT)
+        print ('\n%s\n' % sphinx_build_command)
+        subprocess.call(sphinx_build_command, shell=True)
+
     sys.exit()
 
+
 if __name__ == '__main__':
     main()