From e20d306ffa8a935212715b58f5ff71e589a76c39 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Sat, 30 Jul 2016 18:39:22 +1000 Subject: Cleanup: pep8 --- doc/python_api/sphinx_changelog_gen.py | 113 ++++++++------- doc/python_api/sphinx_doc_gen.py | 257 +++++++++++++++++++-------------- 2 files changed, 207 insertions(+), 163 deletions(-) (limited to 'doc/python_api') diff --git a/doc/python_api/sphinx_changelog_gen.py b/doc/python_api/sphinx_changelog_gen.py index 0b083c31c58..4cbb418e326 100644 --- a/doc/python_api/sphinx_changelog_gen.py +++ b/doc/python_api/sphinx_changelog_gen.py @@ -48,7 +48,8 @@ python doc/python_api/sphinx_changelog_gen.py -- \ ''' {"module.name": {"parent.class": - {"basic_type", "member_name": ("Name", type, range, length, default, descr, f_args, f_arg_types, f_ret_types)}, ... + {"basic_type", "member_name": + ("Name", type, range, length, default, descr, f_args, f_arg_types, f_ret_types)}, ... }, ... } ''' @@ -99,34 +100,34 @@ def api_dump(): prop_range = None dump_class[prop_id] = ( - "prop_rna", # basic_type - prop.name, # name - prop_type, # type - prop_range, # range - prop_length, # length - prop.default, # default - prop.description, # descr - Ellipsis, # f_args - Ellipsis, # f_arg_types - Ellipsis, # f_ret_types - ) + "prop_rna", # basic_type + prop.name, # name + prop_type, # type + prop_range, # range + prop_length, # length + prop.default, # default + prop.description, # descr + Ellipsis, # f_args + Ellipsis, # f_arg_types + Ellipsis, # f_ret_types + ) del props # python props, tricky since we dont know much about them. for prop_id, attr in struct_info.get_py_properties(): dump_class[prop_id] = ( - "prop_py", # basic_type - Ellipsis, # name - Ellipsis, # type - Ellipsis, # range - Ellipsis, # length - Ellipsis, # default - attr.__doc__, # descr - Ellipsis, # f_args - Ellipsis, # f_arg_types - Ellipsis, # f_ret_types - ) + "prop_py", # basic_type + Ellipsis, # name + Ellipsis, # type + Ellipsis, # range + Ellipsis, # length + Ellipsis, # default + attr.__doc__, # descr + Ellipsis, # f_args + Ellipsis, # f_arg_types + Ellipsis, # f_ret_types + ) # kludge func -> props funcs = [(func.identifier, func) for func in struct_info.functions] @@ -137,17 +138,17 @@ def api_dump(): func_args_type = tuple([prop.type for prop in func.args]) dump_class[func_id] = ( - "func_rna", # basic_type - Ellipsis, # name - Ellipsis, # type - Ellipsis, # range - Ellipsis, # length - Ellipsis, # default - func.description, # descr - func_args_ids, # f_args - func_args_type, # f_arg_types - func_ret_types, # f_ret_types - ) + "func_rna", # basic_type + Ellipsis, # name + Ellipsis, # type + Ellipsis, # range + Ellipsis, # length + Ellipsis, # default + func.description, # descr + func_args_ids, # f_args + func_args_type, # f_arg_types + func_ret_types, # f_ret_types + ) del funcs # kludge func -> props @@ -158,17 +159,17 @@ def api_dump(): func_args_ids = tuple(inspect.getargspec(attr).args) dump_class[func_id] = ( - "func_py", # basic_type - Ellipsis, # name - Ellipsis, # type - Ellipsis, # range - Ellipsis, # length - Ellipsis, # default - attr.__doc__, # descr - func_args_ids, # f_args - Ellipsis, # f_arg_types - Ellipsis, # f_ret_types - ) + "func_py", # basic_type + Ellipsis, # name + Ellipsis, # type + Ellipsis, # range + Ellipsis, # length + Ellipsis, # default + attr.__doc__, # descr + func_args_ids, # f_args + Ellipsis, # f_arg_types + Ellipsis, # f_ret_types + ) del funcs import pprint @@ -336,15 +337,19 @@ def main(): parser = argparse.ArgumentParser(description=usage_text, epilog=epilog) - parser.add_argument("--dump", dest="dump", action='store_true', - help="When set the api will be dumped into blender_version.py") - - parser.add_argument("--api_from", dest="api_from", metavar='FILE', - help="File to compare from (previous version)") - parser.add_argument("--api_to", dest="api_to", metavar='FILE', - help="File to compare from (current)") - parser.add_argument("--api_out", dest="api_out", metavar='FILE', - help="Output sphinx changelog") + parser.add_argument( + "--dump", dest="dump", action='store_true', + help="When set the api will be dumped into blender_version.py") + + parser.add_argument( + "--api_from", dest="api_from", metavar='FILE', + help="File to compare from (previous version)") + parser.add_argument( + "--api_to", dest="api_to", metavar='FILE', + help="File to compare from (current)") + parser.add_argument( + "--api_out", dest="api_out", metavar='FILE', + help="Output sphinx changelog") args = parser.parse_args(argv) # In this example we wont use the args diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index 74ff23ee2a3..88dcd73ca4c 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -181,15 +181,13 @@ def handle_args(): dest="log", default=False, action='store_true', - help=( - "Log the output of the api dump and sphinx|latex " - "warnings and errors (default=False).\n" - "If given, save logs in:\n" - "* OUTPUT_DIR/.bpy.log\n" - "* OUTPUT_DIR/.sphinx-build.log\n" - "* OUTPUT_DIR/.sphinx-build_pdf.log\n" - "* OUTPUT_DIR/.latex_make.log", - ), + help="Log the output of the api dump and sphinx|latex " + "warnings and errors (default=False).\n" + "If given, save logs in:\n" + "* OUTPUT_DIR/.bpy.log\n" + "* OUTPUT_DIR/.sphinx-build.log\n" + "* OUTPUT_DIR/.sphinx-build_pdf.log\n" + "* OUTPUT_DIR/.latex_make.log", required=False) # parse only the args passed after '--' @@ -228,8 +226,8 @@ if not ARGS.partial: else: # can manually edit this too: - #FILTER_BPY_OPS = ("import.scene", ) # allow - #FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID") # allow + # FILTER_BPY_OPS = ("import.scene", ) # allow + # FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID") # allow EXCLUDE_INFO_DOCS = True EXCLUDE_MODULES = [ "aud", @@ -275,7 +273,7 @@ else: "freestyle.shaders", "freestyle.types", "freestyle.utils", - ] + ] # ------ # Filter @@ -301,7 +299,9 @@ else: del m del fnmatch - BPY_LOGGER.debug("Partial Doc Build, Skipping: %s\n" % "\n ".join(sorted(EXCLUDE_MODULES))) + BPY_LOGGER.debug( + "Partial Doc Build, Skipping: %s\n" % + "\n ".join(sorted(EXCLUDE_MODULES))) # # done filtering @@ -340,7 +340,7 @@ EXTRA_SOURCE_FILES = ( "../examples/bge.texture.py", "../examples/bmesh.ops.1.py", "../examples/bpy.app.translations.py", - ) +) # examples @@ -357,52 +357,59 @@ 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_tutorial_addon.rst", "Blender/Python Addon Tutorial: a step by step guide on how to write an addon from scratch"), - ("info_api_reference.rst", "Blender/Python API Reference Usage: examples of how to use the API reference docs"), - ("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"), - ) + ("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_tutorial_addon.rst", + "Blender/Python Addon Tutorial: a step by step guide on how to write an addon from scratch"), + ("info_api_reference.rst", + "Blender/Python API Reference Usage: examples of how to use the API reference docs"), + ("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", } - } +} MODULE_GROUPING = { "bmesh.types": ( - ("Base Mesh Type", '-'), - "BMesh", - ("Mesh Elements", '-'), - "BMVert", - "BMEdge", - "BMFace", - "BMLoop", - ("Sequence Accessors", '-'), - "BMElemSeq", - "BMVertSeq", - "BMEdgeSeq", - "BMFaceSeq", - "BMLoopSeq", - "BMIter", - ("Selection History", '-'), - "BMEditSelSeq", - "BMEditSelIter", - ("Custom-Data Layer Access", '-'), - "BMLayerAccessVert", - "BMLayerAccessEdge", - "BMLayerAccessFace", - "BMLayerAccessLoop", - "BMLayerCollection", - "BMLayerItem", - ("Custom-Data Layer Types", '-'), - "BMLoopUV", - "BMDeformVert" - ) - } + ("Base Mesh Type", '-'), + "BMesh", + ("Mesh Elements", '-'), + "BMVert", + "BMEdge", + "BMFace", + "BMLoop", + ("Sequence Accessors", '-'), + "BMElemSeq", + "BMVertSeq", + "BMEdgeSeq", + "BMFaceSeq", + "BMLoopSeq", + "BMIter", + ("Selection History", '-'), + "BMEditSelSeq", + "BMEditSelIter", + ("Custom-Data Layer Access", '-'), + "BMLayerAccessVert", + "BMLayerAccessEdge", + "BMLayerAccessFace", + "BMLayerAccessLoop", + "BMLayerCollection", + "BMLayerItem", + ("Custom-Data Layer Types", '-'), + "BMLoopUV", + "BMDeformVert" + ) +} # --------------------configure compile time options---------------------------- @@ -478,10 +485,10 @@ MethodDescriptorType = type(dict.get) GetSetDescriptorType = type(int.real) StaticMethodType = type(staticmethod(lambda: None)) from types import ( - MemberDescriptorType, - MethodType, - FunctionType, - ) + MemberDescriptorType, + MethodType, + FunctionType, +) _BPY_STRUCT_FAKE = "bpy_struct" _BPY_PROP_COLLECTION_FAKE = "bpy_prop_collection" @@ -501,7 +508,7 @@ escape_rst.trans = str.maketrans({ "|": "\\|", "*": "\\*", "\\": "\\\\", - }) +}) def is_struct_seq(value): @@ -846,7 +853,8 @@ def pymodule2sphinx(basepath, module_name, module, title): # naughty, we also add getset's into PyStructs, this is not typical py but also not incorrect. # type_name is only used for examples and messages - type_name = str(type(module)).strip("<>").split(" ", 1)[-1][1:-1] # "" --> bpy.app.handlers + # "" --> bpy.app.handlers + type_name = str(type(module)).strip("<>").split(" ", 1)[-1][1:-1] if type(descr) == types.GetSetDescriptorType: py_descr2sphinx("", fw, descr, module_name, type_name, key) attribute_set.add(key) @@ -907,7 +915,8 @@ def pymodule2sphinx(basepath, module_name, module, title): for attribute, value, value_type in module_dir_value_type: if value_type == FunctionType: pyfunc2sphinx("", fw, module_name, None, attribute, value, is_class=False) - elif value_type in {types.BuiltinMethodType, types.BuiltinFunctionType}: # both the same at the moment but to be future proof + # both the same at the moment but to be future proof + elif value_type in {types.BuiltinMethodType, types.BuiltinFunctionType}: # note: can't get args from these, so dump the string as is # this means any module used like this must have fully formatted docstrings. py_c_func2sphinx("", fw, module_name, None, attribute, value, is_class=False) @@ -1086,7 +1095,8 @@ def pycontext2sphinx(basepath): fw("\n") fw("The context members available depend on the area of blender which is currently being accessed.\n") fw("\n") - fw("Note that all context values are readonly, but may be modified through the data api or by running operators\n\n") + fw("Note that all context values are readonly,\n") + fw("but may be modified through the data api or by running operators\n\n") def write_contex_cls(): @@ -1109,7 +1119,8 @@ def pycontext2sphinx(basepath): if prop.identifier in struct_blacklist: continue - type_descr = prop.get_type_description(class_fmt=":class:`bpy.types.%s`", collection_id=_BPY_PROP_COLLECTION_ID) + type_descr = prop.get_type_description( + class_fmt=":class:`bpy.types.%s`", collection_id=_BPY_PROP_COLLECTION_ID) fw(".. data:: %s\n\n" % prop.identifier) if prop.description: fw(" %s\n\n" % prop.description) @@ -1165,7 +1176,9 @@ def pycontext2sphinx(basepath): # for member in sorted(unique): # print(' "%s": ("", False),' % member) if len(context_type_map) > len(unique): - raise Exception("Some types are not used: %s" % str([member for member in context_type_map if member not in unique])) + raise Exception( + "Some types are not used: %s" % + str([member for member in context_type_map if member not in unique])) else: pass # will have raised an error above @@ -1244,11 +1257,11 @@ def pyrna2sphinx(basepath): fw(ident + ":%s%s: %s\n" % (id_type, identifier, type_descr)) def write_struct(struct): - #if not struct.identifier.startswith("Sc") and not struct.identifier.startswith("I"): - # return + # if not struct.identifier.startswith("Sc") and not struct.identifier.startswith("I"): + # return - #if not struct.identifier == "Object": - # return + # if not struct.identifier == "Object": + # return filepath = os.path.join(basepath, "bpy.types.%s.rst" % struct.identifier) file = open(filepath, "w", encoding="utf-8") @@ -1289,7 +1302,11 @@ def pyrna2sphinx(basepath): fw(", ".join((":class:`%s`" % base_id) for base_id in base_ids)) fw("\n\n") - subclass_ids = [s.identifier for s in structs.values() if s.base is struct if not rna_info.rna_id_ignore(s.identifier)] + subclass_ids = [ + s.identifier for s in structs.values() + if s.base is struct + if not rna_info.rna_id_ignore(s.identifier) + ] subclass_ids.sort() if subclass_ids: fw("subclasses --- \n" + ", ".join((":class:`%s`" % s) for s in subclass_ids) + "\n\n") @@ -1350,7 +1367,8 @@ def pyrna2sphinx(basepath): for func in struct.functions: args_str = ", ".join(prop.get_arg_default(force=False) for prop in func.args) - fw(" .. %s:: %s(%s)\n\n" % ("classmethod" if func.is_classmethod else "method", func.identifier, args_str)) + fw(" .. %s:: %s(%s)\n\n" % + ("classmethod" if func.is_classmethod else "method", func.identifier, args_str)) fw(" %s\n\n" % func.description) for prop in func.args: @@ -1361,8 +1379,10 @@ def pyrna2sphinx(basepath): elif func.return_values: # multiple return values fw(" :return (%s):\n" % ", ".join(prop.identifier for prop in func.return_values)) for prop in func.return_values: - # TODO, pyrna_enum2sphinx for multiple return values... actually dont think we even use this but still!!! - type_descr = prop.get_type_description(as_ret=True, class_fmt=":class:`%s`", collection_id=_BPY_PROP_COLLECTION_ID) + # TODO, pyrna_enum2sphinx for multiple return values... actually dont + # think we even use this but still!!! + type_descr = prop.get_type_description( + as_ret=True, class_fmt=":class:`%s`", collection_id=_BPY_PROP_COLLECTION_ID) descr = prop.description if not descr: descr = prop.name @@ -1398,7 +1418,10 @@ def pyrna2sphinx(basepath): del lines[:] if _BPY_STRUCT_FAKE: - descr_items = [(key, descr) for key, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()) if not key.startswith("__")] + descr_items = [ + (key, descr) for key, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()) + if not key.startswith("__") + ] if _BPY_STRUCT_FAKE: for key, descr in descr_items: @@ -1494,19 +1517,28 @@ def pyrna2sphinx(basepath): fw("\n") if use_subclasses: - subclass_ids = [s.identifier for s in structs.values() if s.base is None if not rna_info.rna_id_ignore(s.identifier)] + subclass_ids = [ + s.identifier for s in structs.values() + if s.base is None + if not rna_info.rna_id_ignore(s.identifier) + ] if subclass_ids: fw("subclasses --- \n" + ", ".join((":class:`%s`" % s) for s in sorted(subclass_ids)) + "\n\n") fw(".. class:: %s\n\n" % class_name) fw(" %s\n\n" % descr_str) fw(" .. note::\n\n") - fw(" Note that bpy.types.%s is not actually available from within blender, it only exists for the purpose of documentation.\n\n" % class_name) + fw(" Note that bpy.types.%s is not actually available from within Blender,\n" + " it only exists for the purpose of documentation.\n\n" % class_name) - descr_items = [(key, descr) for key, descr in sorted(class_value.__dict__.items()) if not key.startswith("__")] + descr_items = [ + (key, descr) for key, descr in sorted(class_value.__dict__.items()) + if not key.startswith("__") + ] for key, descr in descr_items: - if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet + # GetSetDescriptorType, GetSetDescriptorType's are not documented yet + if type(descr) == MethodDescriptorType: py_descr2sphinx(" ", fw, descr, "bpy.types", class_name, key) for key, descr in descr_items: @@ -1517,11 +1549,15 @@ def pyrna2sphinx(basepath): # write fake classes if _BPY_STRUCT_FAKE: class_value = bpy.types.Struct.__bases__[0] - fake_bpy_type(class_value, _BPY_STRUCT_FAKE, "built-in base class for all classes in bpy.types.", use_subclasses=True) + fake_bpy_type( + class_value, _BPY_STRUCT_FAKE, + "built-in base class for all classes in bpy.types.", use_subclasses=True) if _BPY_PROP_COLLECTION_FAKE: class_value = bpy.data.objects.__class__ - fake_bpy_type(class_value, _BPY_PROP_COLLECTION_FAKE, "built-in class used for all collections.", use_subclasses=False) + fake_bpy_type( + class_value, _BPY_PROP_COLLECTION_FAKE, + "built-in class used for all collections.", use_subclasses=False) # operators def write_ops(): @@ -1633,11 +1669,13 @@ def write_rst_contents(basepath): fw(title_string("Blender Documentation Contents", "%", double=True)) fw("\n") - fw("Welcome, this document is an API reference for Blender %s, built %s.\n" % (BLENDER_VERSION_DOTS, BLENDER_DATE)) + fw("Welcome, this document is an API reference for Blender %s, built %s.\n" % + (BLENDER_VERSION_DOTS, BLENDER_DATE)) fw("\n") # fw("`A PDF version of this document is also available <%s>`_\n" % BLENDER_PDF_FILENAME) - fw("This site can be downloaded for offline use `Download the full Documentation (zipped HTML files) <%s>`_\n" % BLENDER_ZIP_FILENAME) + fw("This site can be downloaded for offline use `Download the full Documentation (zipped HTML files) <%s>`_\n" % + BLENDER_ZIP_FILENAME) fw("\n") @@ -1670,7 +1708,7 @@ def write_rst_contents(basepath): # C modules "bpy.props", - ) + ) for mod in app_modules: if mod not in EXCLUDE_MODULES: @@ -1693,7 +1731,7 @@ def write_rst_contents(basepath): "aud", "bpy_extras", # bmesh, submodules are in own page "bmesh", - ) + ) for mod in standalone_modules: if mod not in EXCLUDE_MODULES: @@ -1731,7 +1769,8 @@ def write_rst_contents(basepath): fw(" * mesh creation and editing functions\n") fw(" \n") fw(" These parts of the API are relatively stable and are unlikely to change significantly\n") - fw(" * data API, access to attributes of blender data such as mesh verts, material color, timeline frames and scene objects\n") + fw(" * data API, access to attributes of blender data such as mesh verts, material color,\n") + fw(" timeline frames and scene objects\n") fw(" * user interface functions for defining buttons, creation of menus, headers, panels\n") fw(" * render engine integration\n") fw(" * modules: bgl, mathutils & game engine.\n") @@ -1823,36 +1862,36 @@ def write_rst_importable_modules(basepath): ''' importable_modules = { # python_modules - "bpy.path" : "Path Utilities", - "bpy.utils" : "Utilities", - "bpy_extras" : "Extra Utilities", + "bpy.path": "Path Utilities", + "bpy.utils": "Utilities", + "bpy_extras": "Extra Utilities", # C_modules - "aud" : "Audio System", - "blf" : "Font Drawing", - "gpu.offscreen" : "GPU Off-Screen Buffer", - "bmesh" : "BMesh Module", - "bmesh.types" : "BMesh Types", - "bmesh.utils" : "BMesh Utilities", - "bmesh.geometry" : "BMesh Geometry Utilities", - "bpy.app" : "Application Data", - "bpy.app.handlers" : "Application Handlers", - "bpy.app.translations" : "Application Translations", - "bpy.props" : "Property Definitions", - "mathutils" : "Math Types & Utilities", - "mathutils.geometry" : "Geometry Utilities", - "mathutils.bvhtree" : "BVHTree Utilities", - "mathutils.kdtree" : "KDTree Utilities", + "aud": "Audio System", + "blf": "Font Drawing", + "gpu.offscreen": "GPU Off-Screen Buffer", + "bmesh": "BMesh Module", + "bmesh.types": "BMesh Types", + "bmesh.utils": "BMesh Utilities", + "bmesh.geometry": "BMesh Geometry Utilities", + "bpy.app": "Application Data", + "bpy.app.handlers": "Application Handlers", + "bpy.app.translations": "Application Translations", + "bpy.props": "Property Definitions", + "mathutils": "Math Types & Utilities", + "mathutils.geometry": "Geometry Utilities", + "mathutils.bvhtree": "BVHTree Utilities", + "mathutils.kdtree": "KDTree Utilities", "mathutils.interpolate": "Interpolation Utilities", - "mathutils.noise" : "Noise Utilities", - "freestyle" : "Freestyle Module", - "freestyle.types" : "Freestyle Types", - "freestyle.predicates" : "Freestyle Predicates", - "freestyle.functions" : "Freestyle Functions", - "freestyle.chainingiterators" : "Freestyle Chaining Iterators", - "freestyle.shaders" : "Freestyle Shaders", - "freestyle.utils" : "Freestyle Utilities", - } + "mathutils.noise": "Noise Utilities", + "freestyle": "Freestyle Module", + "freestyle.types": "Freestyle Types", + "freestyle.predicates": "Freestyle Predicates", + "freestyle.functions": "Freestyle Functions", + "freestyle.chainingiterators": "Freestyle Chaining Iterators", + "freestyle.shaders": "Freestyle Shaders", + "freestyle.utils": "Freestyle Utilities", + } for mod_name, mod_descr in importable_modules.items(): if mod_name not in EXCLUDE_MODULES: module = __import__(mod_name, -- cgit v1.2.3 From 0ec1be18160db011e3ca052d324a91a5de4c1e9d Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Sun, 31 Jul 2016 14:31:39 +1000 Subject: Cleanup: capitalize Blender & Python --- doc/python_api/sphinx_doc_gen.py | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'doc/python_api') diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index 88dcd73ca4c..cb4605e41c0 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -24,7 +24,7 @@ SCRIPT_HELP_MSG = """ API dump in RST files --------------------- - Run this script from blenders root path once you have compiled blender + Run this script from Blender's root path once you have compiled Blender ./blender.bin --background -noaudio --python doc/python_api/sphinx_doc_gen.py @@ -61,14 +61,14 @@ Sphinx: PDF generation """ try: - import bpy # blender module + import bpy # Blender module except ImportError: print("\nERROR: this script must run from inside Blender") print(SCRIPT_HELP_MSG) import sys sys.exit() -import rna_info # blender module +import rna_info # Blender module def rna_info_BuildRNAInfo_cache(): @@ -358,9 +358,9 @@ RST_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "rst")) # stored in ./rst/info_* INFO_DOCS = ( ("info_quickstart.rst", - "Blender/Python Quickstart: new to blender/scripting and want to get your feet wet?"), + "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"), + "Blender/Python API Overview: a more complete explanation of Python integration"), ("info_tutorial_addon.rst", "Blender/Python Addon Tutorial: a step by step guide on how to write an addon from scratch"), ("info_api_reference.rst", @@ -368,7 +368,7 @@ INFO_DOCS = ( ("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"), + "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"), ) @@ -753,7 +753,7 @@ def py_c_func2sphinx(ident, fw, module_name, type_name, identifier, py_func, is_ def pyprop2sphinx(ident, fw, identifier, py_prop): ''' - python property to sphinx + Python property to sphinx ''' # readonly properties use "data" directive, variables use "attribute" directive if py_prop.fset is None: @@ -982,7 +982,7 @@ def pymodule2sphinx(basepath, module_name, module, title): if type(descr) == ClassMethodDescriptorType: py_descr2sphinx(" ", fw, descr, module_name, type_name, key) - # needed for pure python classes + # needed for pure Python classes for key, descr in descr_items: if type(descr) == FunctionType: pyfunc2sphinx(" ", fw, module_name, type_name, key, descr, is_class=True) @@ -1005,7 +1005,7 @@ def pymodule2sphinx(basepath, module_name, module, title): file.close() -# Changes in blender will force errors here +# Changes in Blender will force errors here context_type_map = { "active_base": ("ObjectBase", False), "active_bone": ("EditBone", False), @@ -1093,7 +1093,7 @@ def pycontext2sphinx(basepath): fw(title_string("Context Access (bpy.context)", "=")) fw(".. module:: bpy.context\n") fw("\n") - fw("The context members available depend on the area of blender which is currently being accessed.\n") + fw("The context members available depend on the area of Blender which is currently being accessed.\n") fw("\n") fw("Note that all context values are readonly,\n") fw("but may be modified through the data api or by running operators\n\n") @@ -1140,7 +1140,7 @@ def pycontext2sphinx(basepath): del write_contex_cls # end - # nasty, get strings directly from blender because there is no other way to get it + # nasty, get strings directly from Blender because there is no other way to get it import ctypes context_strings = ( @@ -1357,7 +1357,7 @@ def pyrna2sphinx(basepath): fw(" :type: %s\n\n" % type_descr) - # python attributes + # Python attributes py_properties = struct.get_py_properties() py_prop = None for identifier, py_prop in py_properties: @@ -1395,7 +1395,7 @@ def pyrna2sphinx(basepath): fw("\n") - # python methods + # Python methods py_funcs = struct.get_py_functions() py_func = None @@ -1769,7 +1769,7 @@ def write_rst_contents(basepath): fw(" * mesh creation and editing functions\n") fw(" \n") fw(" These parts of the API are relatively stable and are unlikely to change significantly\n") - fw(" * data API, access to attributes of blender data such as mesh verts, material color,\n") + fw(" * data API, access to attributes of Blender data such as mesh verts, material color,\n") fw(" timeline frames and scene objects\n") fw(" * user interface functions for defining buttons, creation of menus, headers, panels\n") fw(" * render engine integration\n") @@ -1842,11 +1842,11 @@ def write_rst_data(basepath): fw(title_string("Data Access (bpy.data)", "=")) fw(".. module:: bpy\n") fw("\n") - fw("This module is used for all blender/python access.\n") + fw("This module is used for all Blender/Python access.\n") fw("\n") fw(".. data:: data\n") fw("\n") - fw(" Access to blenders internal data\n") + fw(" Access to Blender's internal data\n") fw("\n") fw(" :type: :class:`bpy.types.BlendData`\n") fw("\n") @@ -1861,7 +1861,7 @@ def write_rst_importable_modules(basepath): Write the rst files of importable modules ''' importable_modules = { - # python_modules + # Python_modules "bpy.path": "Path Utilities", "bpy.utils": "Utilities", "bpy_extras": "Extra Utilities", @@ -1906,7 +1906,7 @@ def copy_handwritten_rsts(basepath): 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 + # TODO put this docs in Blender's code and use import as per modules above handwritten_modules = [ "bge.logic", "bge.render", -- cgit v1.2.3 From 516f890b632a949f1fe544a8483745199bfbe9ad Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Sun, 31 Jul 2016 14:37:25 +1000 Subject: Docs: simplify EXCLUDE_MODULES handling --- doc/python_api/sphinx_doc_gen.py | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) (limited to 'doc/python_api') diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index cb4605e41c0..7e9868f3598 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -222,7 +222,7 @@ if not ARGS.partial: FILTER_BPY_OPS = None FILTER_BPY_TYPES = None EXCLUDE_INFO_DOCS = False - EXCLUDE_MODULES = () + EXCLUDE_MODULES = [] else: # can manually edit this too: @@ -311,19 +311,21 @@ try: __import__("aud") except ImportError: BPY_LOGGER.debug("Warning: Built without 'aud' module, docs incomplete...") - EXCLUDE_MODULES = list(EXCLUDE_MODULES) + ["aud"] + EXCLUDE_MODULES.append("aud") try: __import__("freestyle") except ImportError: BPY_LOGGER.debug("Warning: Built without 'freestyle' module, docs incomplete...") - EXCLUDE_MODULES = list(EXCLUDE_MODULES) + ["freestyle", - "freestyle.chainingiterators", - "freestyle.functions", - "freestyle.predicates", - "freestyle.shaders", - "freestyle.types", - "freestyle.utils"] + EXCLUDE_MODULES.extend([ + "freestyle", + "freestyle.chainingiterators", + "freestyle.functions", + "freestyle.predicates", + "freestyle.shaders", + "freestyle.types", + "freestyle.utils", + ]) # Source files we use, and need to copy to the OUTPUT_DIR # to have working out-of-source builds. -- cgit v1.2.3 From 409316434c42363b5c64c4ce58690d273f61f56e Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Sun, 31 Jul 2016 15:39:30 +1000 Subject: Docs: add initial idprop.types API docs --- doc/python_api/epy/IDProp.py | 132 --------------------------------------- doc/python_api/sphinx_doc_gen.py | 3 + 2 files changed, 3 insertions(+), 132 deletions(-) delete mode 100644 doc/python_api/epy/IDProp.py (limited to 'doc/python_api') diff --git a/doc/python_api/epy/IDProp.py b/doc/python_api/epy/IDProp.py deleted file mode 100644 index 1fc26d7f65b..00000000000 --- a/doc/python_api/epy/IDProp.py +++ /dev/null @@ -1,132 +0,0 @@ -class IDGroup: - """ - The IDGroup Type - ================ - This type supports both iteration and the [] - operator to get child ID properties. - - You can also add new properties using the [] operator. - For example:: - - group['a float!'] = 0.0 - group['an int!'] = 0 - group['a string!'] = "hi!" - group['an array!'] = [0, 0, 1.0, 0] - - group['a subgroup!] = {"float": 0.0, "an int": 1.0, "an array": [1, 2], - "another subgroup": {"a": 0.0, "str": "bleh"}} - - Note that for arrays, the array type defaults to int unless a float is found - while scanning the template list; if any floats are found, then the whole - array is float. Note that double-precision floating point numbers are used for - python-created float ID properties and arrays (though the internal C api does - support single-precision floats, and the python code will read them). - - You can also delete properties with the del operator. For example: - - del group['property'] - - To get the type of a property, use the type() operator, for example:: - - if type(group['bleh']) == str: pass - - To tell if the property is a group or array type, import the Blender.Types module and test - against IDGroupType and IDArrayType, like so:: - - from Blender.Types import IDGroupType, IDArrayType. - - if type(group['bleghr']) == IDGroupType: - (do something) - - @ivar name: The name of the property - @type name: string - """ - - def pop(item): - """ - Pop an item from the group property. - @type item: string - @param item: The item name. - @rtype: can be dict, list, int, float or string. - @return: The removed property. - """ - - def update(updatedict): - """ - Updates items in the dict, similar to normal python - dictionary method .update(). - @type updatedict: dict - @param updatedict: A dict of simple types to derive updated/new IDProperties from. - @rtype: None - @return: None - """ - - def keys(): - """ - Returns a list of the keys in this property group. - @rtype: list of strings. - @return: a list of the keys in this property group. - """ - - def values(): - """ - Returns a list of the values in this property group. - - Note that unless a value is itself a property group or an array, you - cannot change it by changing the values in this list, you must change them - in the parent property group. - - For example, - - group['some_property'] = new_value - - . . .is correct, while, - - values = group.values() - values[0] = new_value - - . . .is wrong. - - @rtype: list of strings. - @return: a list of the values in this property group. - """ - - def iteritems(): - """ - Implements the python dictionary iteritmes method. - - For example:: - - for k, v in group.iteritems(): - print "Property name: " + k - print "Property value: " + str(v) - - @rtype: an iterator that spits out items of the form [key, value] - @return: an iterator. - """ - - def convert_to_pyobject(): - """ - Converts the entire property group to a purely python form. - - @rtype: dict - @return: A python dictionary representing the property group - """ - -class IDArray: - """ - The IDArray Type - ================ - - @ivar type: returns the type of the array, can be either IDP_Int or IDP_Float - """ - - def __getitem__(index): - pass - - def __setitem__(index, value): - pass - - def __len__(): - pass - diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index 7e9868f3598..2a3213e4e6f 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -260,6 +260,7 @@ else: "bpy_extras", "gpu", "gpu.offscreen", + "idprop.types", "mathutils", "mathutils.bvhtree", "mathutils.geometry", @@ -1731,6 +1732,7 @@ def write_rst_contents(basepath): "freestyle", "bgl", "blf", "gpu", "gpu.offscreen", "aud", "bpy_extras", + "idprop.types", # bmesh, submodules are in own page "bmesh", ) @@ -1880,6 +1882,7 @@ def write_rst_importable_modules(basepath): "bpy.app.handlers": "Application Handlers", "bpy.app.translations": "Application Translations", "bpy.props": "Property Definitions", + "idprop.types": "ID Property Access", "mathutils": "Math Types & Utilities", "mathutils.geometry": "Geometry Utilities", "mathutils.bvhtree": "BVHTree Utilities", -- cgit v1.2.3