griefith/test
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Merged changes in the trunk up to revision 44797.

Browse Source 
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
This commit is contained in:
Tamito Kajiyama
2012-03-10 21:56:23 +00:00
parent e9eed190e8 e09ab8883c
commit a2ebfc82db
828 changed files with 28231 additions and 25725 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
doc/python_api/rst/bge.types.rst
View File

@@ -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.

2
doc/python_api/rst/info_best_practice.rst
View File

@@ -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.

2
doc/python_api/rst/info_tips_and_tricks.rst
View File

@@ -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'))

842
doc/python_api/sphinx_doc_gen.py
View File

@@ -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,91 +77,229 @@ 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
# Switch for quick testing
if 1:
# 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-----------------------------------------
"""
# 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",
"bpy.app",
"bpy.app.handlers",
"bpy.path",
"bpy.data",
"bpy.props",
"bpy.utils",
"bpy.context",
"bpy.types", # supports filtering
"bpy.ops", # supports filtering
"bpy_extras",
"bge",
"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.context",
"bpy.data",
"bpy.ops", # supports filtering
"bpy.path",
"bpy.props",
"bpy.types", # supports filtering
"bpy.utils",
"bpy_extras",
"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
# 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
"""
# extra info, not api reference docs
# stored in ./rst/info_*
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_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", },
}
# -----------------------------------------------------------------------------
# configure compile time options
try:
__import__("aud")
except ImportError:
print("Warning: Built without 'aud' module, docs incomplete...")
EXCLUDE_MODULES = EXCLUDE_MODULES + ("aud", )
# 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_*
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 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 = {
# 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
# -------------------------------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")
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")
app_modules = [
"bpy.context", # note: not actually a module
"bpy.data", # note: not actually a module
"bpy.ops",
"bpy.types",
# C modules
if "bpy.props" not in EXCLUDE_MODULES:
fw(" bpy.props.rst\n\n")
# 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,9 +1407,48 @@ def rna2sphinx(BASEPATH):
file.close()
# internal modules
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("\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")
file = open(filepath, "w", encoding="utf-8")
fw = file.write
fw("Types (bpy.types)\n")
fw("=================\n\n")
fw(".. toctree::\n")
fw(" :glob:\n\n")
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")
filepath = os.path.join(basepath, "bpy.ops.rst")
file = open(filepath, "w", encoding="utf-8")
fw = file.write
fw("Operators (bpy.ops)\n")
@@ -1302,21 +1459,15 @@ def rna2sphinx(BASEPATH):
fw(" bpy.ops.*\n\n")
file.close()
if "bpy.types" not in EXCLUDE_MODULES:
filepath = os.path.join(BASEPATH, "bpy.types.rst")
file = open(filepath, "w", encoding="utf-8")
fw = file.write
fw("Types (bpy.types)\n")
fw("=================\n\n")
fw(".. toctree::\n")
fw(" :glob:\n\n")
fw(" bpy.types.*\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
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)
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)
# 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):
try:
os.mkdir(basepath)
except:
pass
# sphinx setup
write_sphinx_conf_py(basepath)
# main page
write_rst_contents(basepath)
# 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)
pycontext2sphinx(basepath)
# python modules
if "bpy.utils" not in EXCLUDE_MODULES:
from bpy import utils as module
pymodule2sphinx(BASEPATH, "bpy.utils", module, "Utilities")
# 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)
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)
shutil.copy2(os.path.join(RST_DIR, "change_log.rst"), BASEPATH)
if not EXCLUDE_INFO_DOCS:
for info, info_desc in INFO_DOCS:
shutil.copy2(os.path.join(RST_DIR, info), BASEPATH)
if 0:
filepath = os.path.join(BASEPATH, "bpy.rst")
file = open(filepath, "w", encoding="utf-8")
fw = file.write
fw("\n")
title = ":mod:`bpy` --- Blender Python Module"
write_title(fw, title, "=")
fw(".. module:: bpy.types\n\n")
file.close()
# bpy.types and bpy.ops
pyrna2sphinx(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)
import filecmp
sphinx_in_files = set(os.listdir(SPHINX_IN))
sphinx_in_tmp_files = set(os.listdir(SPHINX_IN_TMP))
# 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))
# 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)
do_copy = True
if f in sphinx_in_files:
if filecmp.cmp(f_from, f_to):
do_copy = False
if do_copy:
print("\tupdating: %s" % f)
shutil.copy(f_from, f_to)
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")
# dirs preparation
for dir_path in [ARGS.output_dir, SPHINX_IN]:
if not os.path.exists(dir_path):
os.mkdir(dir_path)
# 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)
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)
# 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_dir, True)
rna2sphinx(sphinx_in_tmp_dir)
if not _BPY_FULL_REBUILD:
import filecmp
# 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))
# 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))
# 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
if do_copy:
print("\tupdating: %s" % f)
shutil.copy(f_from, f_to)
'''else:
print("\tkeeping: %s" % f) # eh, not that useful'''
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()