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( + "--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( + "--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,