diff options
author | Tamito Kajiyama <rd6t-kjym@asahi-net.or.jp> | 2012-03-11 01:56:23 +0400 |
---|---|---|
committer | Tamito Kajiyama <rd6t-kjym@asahi-net.or.jp> | 2012-03-11 01:56:23 +0400 |
commit | a2ebfc82dbe954acc432ae017ac62a30a11b6a16 (patch) | |
tree | 8cf8bf458d14a26849dbee6af312ff9361029b90 /doc/python_api | |
parent | e9eed190e83eb351aeb435d21287eaf37fcffeb0 (diff) | |
parent | e09ab8883ce0e41add94058ecd4045ac5efa74c6 (diff) |
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
Diffstat (limited to 'doc/python_api')
-rw-r--r-- | doc/python_api/rst/bge.types.rst | 14 | ||||
-rw-r--r-- | doc/python_api/rst/info_best_practice.rst | 2 | ||||
-rw-r--r-- | doc/python_api/rst/info_tips_and_tricks.rst | 2 | ||||
-rw-r--r-- | doc/python_api/sphinx_doc_gen.py | 798 |
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§ion=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"\ + "§ion=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() |