archive/blender-archive
Archived
1
1
Fork 0
Code Pull Requests Packages Activity

Cleanup: pep8

Browse Source
This commit is contained in:
Campbell Barton
2016-07-30 18:39:22 +10:00
parent de103497c4
commit e20d306ffa
2 changed files with 206 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
doc/python_api/sphinx_changelog_gen.py
View File

@@ -48,7 +48,8 @@ python doc/python_api/sphinx_changelog_gen.py -- \
''' '''
{"module.name": {"module.name":
{"parent.class": {"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)}, ...
}, ... }, ...
} }
''' '''
@@ -336,14 +337,18 @@ def main():
parser = argparse.ArgumentParser(description=usage_text, epilog=epilog) parser = argparse.ArgumentParser(description=usage_text, epilog=epilog)
parser.add_argument("--dump", dest="dump", action='store_true', parser.add_argument(
"--dump", dest="dump", action='store_true',
help="When set the api will be dumped into blender_version.py") help="When set the api will be dumped into blender_version.py")
parser.add_argument("--api_from", dest="api_from", metavar='FILE', parser.add_argument(
"--api_from", dest="api_from", metavar='FILE',
help="File to compare from (previous version)") help="File to compare from (previous version)")
parser.add_argument("--api_to", dest="api_to", metavar='FILE', parser.add_argument(
"--api_to", dest="api_to", metavar='FILE',
help="File to compare from (current)") help="File to compare from (current)")
parser.add_argument("--api_out", dest="api_out", metavar='FILE', parser.add_argument(
"--api_out", dest="api_out", metavar='FILE',
help="Output sphinx changelog") help="Output sphinx changelog")
args = parser.parse_args(argv) # In this example we wont use the args args = parser.parse_args(argv) # In this example we wont use the args

171
doc/python_api/sphinx_doc_gen.py
View File

@@ -181,15 +181,13 @@ def handle_args():
dest="log", dest="log",
default=False, default=False,
action='store_true', action='store_true',
help=( help="Log the output of the api dump and sphinx|latex "
"Log the output of the api dump and sphinx|latex "
"warnings and errors (default=False).\n" "warnings and errors (default=False).\n"
"If given, save logs in:\n" "If given, save logs in:\n"
"* OUTPUT_DIR/.bpy.log\n" "* OUTPUT_DIR/.bpy.log\n"
"* OUTPUT_DIR/.sphinx-build.log\n" "* OUTPUT_DIR/.sphinx-build.log\n"
"* OUTPUT_DIR/.sphinx-build_pdf.log\n" "* OUTPUT_DIR/.sphinx-build_pdf.log\n"
"* OUTPUT_DIR/.latex_make.log", "* OUTPUT_DIR/.latex_make.log",
),
required=False) required=False)
# parse only the args passed after '--' # parse only the args passed after '--'
@@ -228,8 +226,8 @@ if not ARGS.partial:
else: else:
# can manually edit this too: # can manually edit this too:
#FILTER_BPY_OPS = ("import.scene", ) # allow # FILTER_BPY_OPS = ("import.scene", ) # allow
#FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID") # allow # FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID") # allow
EXCLUDE_INFO_DOCS = True EXCLUDE_INFO_DOCS = True
EXCLUDE_MODULES = [ EXCLUDE_MODULES = [
"aud", "aud",
@@ -301,7 +299,9 @@ else:
del m del m
del fnmatch 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 # done filtering
@@ -340,7 +340,7 @@ EXTRA_SOURCE_FILES = (
"../examples/bge.texture.py", "../examples/bge.texture.py",
"../examples/bmesh.ops.1.py", "../examples/bmesh.ops.1.py",
"../examples/bpy.app.translations.py", "../examples/bpy.app.translations.py",
) )
# examples # examples
@@ -357,20 +357,27 @@ RST_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "rst"))
# extra info, not api reference docs # extra info, not api reference docs
# stored in ./rst/info_* # stored in ./rst/info_*
INFO_DOCS = ( INFO_DOCS = (
("info_quickstart.rst", "Blender/Python Quickstart: new to blender/scripting and want to get your feet wet?"), ("info_quickstart.rst",
("info_overview.rst", "Blender/Python API Overview: a more complete explanation of python integration"), "Blender/Python Quickstart: new to blender/scripting and want to get your feet wet?"),
("info_tutorial_addon.rst", "Blender/Python Addon Tutorial: a step by step guide on how to write an addon from scratch"), ("info_overview.rst",
("info_api_reference.rst", "Blender/Python API Reference Usage: examples of how to use the API reference docs"), "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_tutorial_addon.rst",
("info_tips_and_tricks.rst", "Tips and Tricks: Hints to help you while writing scripts for blender"), "Blender/Python Addon Tutorial: a step by step guide on how to write an addon from scratch"),
("info_gotcha.rst", "Gotcha's: some of the problems you may come up against when writing scripts"), ("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. # only support for properties atm.
RNA_BLACKLIST = { RNA_BLACKLIST = {
# XXX messes up PDF!, really a bug but for now just workaround. # XXX messes up PDF!, really a bug but for now just workaround.
"UserPreferencesSystem": {"language", } "UserPreferencesSystem": {"language", }
} }
MODULE_GROUPING = { MODULE_GROUPING = {
"bmesh.types": ( "bmesh.types": (
@@ -402,7 +409,7 @@ MODULE_GROUPING = {
"BMLoopUV", "BMLoopUV",
"BMDeformVert" "BMDeformVert"
) )
} }
# --------------------configure compile time options---------------------------- # --------------------configure compile time options----------------------------
@@ -481,7 +488,7 @@ from types import (
MemberDescriptorType, MemberDescriptorType,
MethodType, MethodType,
FunctionType, FunctionType,
) )
_BPY_STRUCT_FAKE = "bpy_struct" _BPY_STRUCT_FAKE = "bpy_struct"
_BPY_PROP_COLLECTION_FAKE = "bpy_prop_collection" _BPY_PROP_COLLECTION_FAKE = "bpy_prop_collection"
@@ -501,7 +508,7 @@ escape_rst.trans = str.maketrans({
"|": "\\|", "|": "\\|",
"*": "\\*", "*": "\\*",
"\\": "\\\\", "\\": "\\\\",
}) })
def is_struct_seq(value): 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. # 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 is only used for examples and messages
type_name = str(type(module)).strip("<>").split(" ", 1)[-1][1:-1] # "<class 'bpy.app.handlers'>" --> bpy.app.handlers # "<class 'bpy.app.handlers'>" --> bpy.app.handlers
type_name = str(type(module)).strip("<>").split(" ", 1)[-1][1:-1]
if type(descr) == types.GetSetDescriptorType: if type(descr) == types.GetSetDescriptorType:
py_descr2sphinx("", fw, descr, module_name, type_name, key) py_descr2sphinx("", fw, descr, module_name, type_name, key)
attribute_set.add(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: for attribute, value, value_type in module_dir_value_type:
if value_type == FunctionType: if value_type == FunctionType:
pyfunc2sphinx("", fw, module_name, None, attribute, value, is_class=False) 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 # 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. # this means any module used like this must have fully formatted docstrings.
py_c_func2sphinx("", fw, module_name, None, attribute, value, is_class=False) py_c_func2sphinx("", fw, module_name, None, attribute, value, is_class=False)
@@ -1086,7 +1095,8 @@ def pycontext2sphinx(basepath):
fw("\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("\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(): def write_contex_cls():
@@ -1109,7 +1119,8 @@ def pycontext2sphinx(basepath):
if prop.identifier in struct_blacklist: if prop.identifier in struct_blacklist:
continue 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) fw(".. data:: %s\n\n" % prop.identifier)
if prop.description: if prop.description:
fw(" %s\n\n" % prop.description) fw(" %s\n\n" % prop.description)
@@ -1165,7 +1176,9 @@ def pycontext2sphinx(basepath):
# for member in sorted(unique): # for member in sorted(unique):
# print(' "%s": ("", False),' % member) # print(' "%s": ("", False),' % member)
if len(context_type_map) > len(unique): 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: else:
pass # will have raised an error above pass # will have raised an error above
@@ -1244,10 +1257,10 @@ def pyrna2sphinx(basepath):
fw(ident + ":%s%s: %s\n" % (id_type, identifier, type_descr)) fw(ident + ":%s%s: %s\n" % (id_type, identifier, type_descr))
def write_struct(struct): def write_struct(struct):
#if not struct.identifier.startswith("Sc") and not struct.identifier.startswith("I"): # if not struct.identifier.startswith("Sc") and not struct.identifier.startswith("I"):
# return # return
#if not struct.identifier == "Object": # if not struct.identifier == "Object":
# return # return
filepath = os.path.join(basepath, "bpy.types.%s.rst" % struct.identifier) filepath = os.path.join(basepath, "bpy.types.%s.rst" % struct.identifier)
@@ -1289,7 +1302,11 @@ def pyrna2sphinx(basepath):
fw(", ".join((":class:`%s`" % base_id) for base_id in base_ids)) fw(", ".join((":class:`%s`" % base_id) for base_id in base_ids))
fw("\n\n") 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() subclass_ids.sort()
if subclass_ids: if subclass_ids:
fw("subclasses --- \n" + ", ".join((":class:`%s`" % s) for s in subclass_ids) + "\n\n") 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: for func in struct.functions:
args_str = ", ".join(prop.get_arg_default(force=False) for prop in func.args) 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) fw(" %s\n\n" % func.description)
for prop in func.args: for prop in func.args:
@@ -1361,8 +1379,10 @@ def pyrna2sphinx(basepath):
elif func.return_values: # multiple return values elif func.return_values: # multiple return values
fw(" :return (%s):\n" % ", ".join(prop.identifier for prop in func.return_values)) fw(" :return (%s):\n" % ", ".join(prop.identifier for prop in func.return_values))
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!!! # TODO, pyrna_enum2sphinx for multiple return values... actually dont
type_descr = prop.get_type_description(as_ret=True, class_fmt=":class:`%s`", collection_id=_BPY_PROP_COLLECTION_ID) # 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 descr = prop.description
if not descr: if not descr:
descr = prop.name descr = prop.name
@@ -1398,7 +1418,10 @@ def pyrna2sphinx(basepath):
del lines[:] del lines[:]
if _BPY_STRUCT_FAKE: 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: if _BPY_STRUCT_FAKE:
for key, descr in descr_items: for key, descr in descr_items:
@@ -1494,19 +1517,28 @@ def pyrna2sphinx(basepath):
fw("\n") fw("\n")
if use_subclasses: 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: if subclass_ids:
fw("subclasses --- \n" + ", ".join((":class:`%s`" % s) for s in sorted(subclass_ids)) + "\n\n") fw("subclasses --- \n" + ", ".join((":class:`%s`" % s) for s in sorted(subclass_ids)) + "\n\n")
fw(".. class:: %s\n\n" % class_name) fw(".. class:: %s\n\n" % class_name)
fw(" %s\n\n" % descr_str) fw(" %s\n\n" % descr_str)
fw(" .. note::\n\n") 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: 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) py_descr2sphinx(" ", fw, descr, "bpy.types", class_name, key)
for key, descr in descr_items: for key, descr in descr_items:
@@ -1517,11 +1549,15 @@ def pyrna2sphinx(basepath):
# write fake classes # write fake classes
if _BPY_STRUCT_FAKE: if _BPY_STRUCT_FAKE:
class_value = bpy.types.Struct.__bases__[0] 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: if _BPY_PROP_COLLECTION_FAKE:
class_value = bpy.data.objects.__class__ 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 # operators
def write_ops(): def write_ops():
@@ -1633,11 +1669,13 @@ def write_rst_contents(basepath):
fw(title_string("Blender Documentation Contents", "%", double=True)) fw(title_string("Blender Documentation Contents", "%", double=True))
fw("\n") 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("\n")
# fw("`A PDF version of this document is also available <%s>`_\n" % BLENDER_PDF_FILENAME) # 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") fw("\n")
@@ -1731,7 +1769,8 @@ def write_rst_contents(basepath):
fw(" * mesh creation and editing functions\n") fw(" * mesh creation and editing functions\n")
fw(" \n") fw(" \n")
fw(" These parts of the API are relatively stable and are unlikely to change significantly\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(" * user interface functions for defining buttons, creation of menus, headers, panels\n")
fw(" * render engine integration\n") fw(" * render engine integration\n")
fw(" * modules: bgl, mathutils & game engine.\n") fw(" * modules: bgl, mathutils & game engine.\n")
@@ -1823,35 +1862,35 @@ def write_rst_importable_modules(basepath):
''' '''
importable_modules = { importable_modules = {
# python_modules # python_modules
"bpy.path" : "Path Utilities", "bpy.path": "Path Utilities",
"bpy.utils" : "Utilities", "bpy.utils": "Utilities",
"bpy_extras" : "Extra Utilities", "bpy_extras": "Extra Utilities",
# C_modules # C_modules
"aud" : "Audio System", "aud": "Audio System",
"blf" : "Font Drawing", "blf": "Font Drawing",
"gpu.offscreen" : "GPU Off-Screen Buffer", "gpu.offscreen": "GPU Off-Screen Buffer",
"bmesh" : "BMesh Module", "bmesh": "BMesh Module",
"bmesh.types" : "BMesh Types", "bmesh.types": "BMesh Types",
"bmesh.utils" : "BMesh Utilities", "bmesh.utils": "BMesh Utilities",
"bmesh.geometry" : "BMesh Geometry Utilities", "bmesh.geometry": "BMesh Geometry Utilities",
"bpy.app" : "Application Data", "bpy.app": "Application Data",
"bpy.app.handlers" : "Application Handlers", "bpy.app.handlers": "Application Handlers",
"bpy.app.translations" : "Application Translations", "bpy.app.translations": "Application Translations",
"bpy.props" : "Property Definitions", "bpy.props": "Property Definitions",
"mathutils" : "Math Types & Utilities", "mathutils": "Math Types & Utilities",
"mathutils.geometry" : "Geometry Utilities", "mathutils.geometry": "Geometry Utilities",
"mathutils.bvhtree" : "BVHTree Utilities", "mathutils.bvhtree": "BVHTree Utilities",
"mathutils.kdtree" : "KDTree Utilities", "mathutils.kdtree": "KDTree Utilities",
"mathutils.interpolate": "Interpolation Utilities", "mathutils.interpolate": "Interpolation Utilities",
"mathutils.noise" : "Noise Utilities", "mathutils.noise": "Noise Utilities",
"freestyle" : "Freestyle Module", "freestyle": "Freestyle Module",
"freestyle.types" : "Freestyle Types", "freestyle.types": "Freestyle Types",
"freestyle.predicates" : "Freestyle Predicates", "freestyle.predicates": "Freestyle Predicates",
"freestyle.functions" : "Freestyle Functions", "freestyle.functions": "Freestyle Functions",
"freestyle.chainingiterators" : "Freestyle Chaining Iterators", "freestyle.chainingiterators": "Freestyle Chaining Iterators",
"freestyle.shaders" : "Freestyle Shaders", "freestyle.shaders": "Freestyle Shaders",
"freestyle.utils" : "Freestyle Utilities", "freestyle.utils": "Freestyle Utilities",
} }
for mod_name, mod_descr in importable_modules.items(): for mod_name, mod_descr in importable_modules.items():
if mod_name not in EXCLUDE_MODULES: if mod_name not in EXCLUDE_MODULES: