Changeset View
Changeset View
Standalone View
Standalone View
doc/python_api/sphinx_doc_gen.py
| Show First 20 Lines • Show All 485 Lines • ▼ Show 20 Lines | if ARGS.log: | ||||
| "-w", SPHINX_BUILD_PDF_LOG, | "-w", SPHINX_BUILD_PDF_LOG, | ||||
| SPHINX_IN, SPHINX_OUT_PDF] | SPHINX_IN, SPHINX_OUT_PDF] | ||||
| sphinx_make_pdf_log = os.path.join(ARGS.output_dir, ".latex_make.log") | sphinx_make_pdf_log = os.path.join(ARGS.output_dir, ".latex_make.log") | ||||
| SPHINX_MAKE_PDF_STDOUT = open(sphinx_make_pdf_log, "w", encoding="utf-8") | SPHINX_MAKE_PDF_STDOUT = open(sphinx_make_pdf_log, "w", encoding="utf-8") | ||||
| # --------------------------------API DUMP-------------------------------------- | # --------------------------------API DUMP-------------------------------------- | ||||
| # lame, python wont give some access | # lame, python won't give some access | ||||
| ClassMethodDescriptorType = type(dict.__dict__['fromkeys']) | ClassMethodDescriptorType = type(dict.__dict__['fromkeys']) | ||||
| MethodDescriptorType = type(dict.get) | MethodDescriptorType = type(dict.get) | ||||
| GetSetDescriptorType = type(int.real) | GetSetDescriptorType = type(int.real) | ||||
| StaticMethodType = type(staticmethod(lambda: None)) | StaticMethodType = type(staticmethod(lambda: None)) | ||||
| from types import ( | from types import ( | ||||
| MemberDescriptorType, | MemberDescriptorType, | ||||
| MethodType, | MethodType, | ||||
| FunctionType, | FunctionType, | ||||
| ▲ Show 20 Lines • Show All 182 Lines • ▼ Show 20 Lines | def pyfunc2sphinx(ident, fw, module_name, type_name, identifier, py_func, is_class=True): | ||||
| if type(py_func) == MethodType: | if type(py_func) == MethodType: | ||||
| return | return | ||||
| arg_str = inspect.formatargspec(*inspect.getfullargspec(py_func)) | arg_str = inspect.formatargspec(*inspect.getfullargspec(py_func)) | ||||
| if not is_class: | if not is_class: | ||||
| func_type = "function" | func_type = "function" | ||||
| # ther rest are class methods | # the rest are class methods | ||||
| elif arg_str.startswith("(self, ") or arg_str == "(self)": | elif arg_str.startswith("(self, ") or arg_str == "(self)": | ||||
| arg_str = "()" if (arg_str == "(self)") else ("(" + arg_str[7:]) | arg_str = "()" if (arg_str == "(self)") else ("(" + arg_str[7:]) | ||||
| func_type = "method" | func_type = "method" | ||||
| elif arg_str.startswith("(cls, "): | elif arg_str.startswith("(cls, "): | ||||
| arg_str = "()" if (arg_str == "(cls)") else ("(" + arg_str[6:]) | arg_str = "()" if (arg_str == "(cls)") else ("(" + arg_str[6:]) | ||||
| func_type = "classmethod" | func_type = "classmethod" | ||||
| else: | else: | ||||
| func_type = "staticmethod" | func_type = "staticmethod" | ||||
| ▲ Show 20 Lines • Show All 117 Lines • ▼ Show 20 Lines | def pymodule2sphinx(basepath, module_name, module, title): | ||||
| fw = file.write | fw = file.write | ||||
| fw(title_string("%s (%s)" % (title, module_name), "=")) | fw(title_string("%s (%s)" % (title, module_name), "=")) | ||||
| fw(".. module:: %s\n\n" % module_name) | fw(".. module:: %s\n\n" % module_name) | ||||
| if module.__doc__: | if module.__doc__: | ||||
| # Note, may contain sphinx syntax, dont mangle! | # Note, may contain sphinx syntax, don't mangle! | ||||
| fw(module.__doc__.strip()) | fw(module.__doc__.strip()) | ||||
| fw("\n\n") | fw("\n\n") | ||||
| write_example_ref("", fw, module_name) | write_example_ref("", fw, module_name) | ||||
| # write submodules | # write submodules | ||||
| # we could also scan files but this ensures __all__ is used correctly | # we could also scan files but this ensures __all__ is used correctly | ||||
| if module_all is not None: | if module_all is not None: | ||||
| ▲ Show 20 Lines • Show All 279 Lines • ▼ Show 20 Lines | def pycontext2sphinx(basepath): | ||||
| 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,\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") | fw("but may be modified through the data api or by running operators\n\n") | ||||
| def write_contex_cls(): | def write_contex_cls(): | ||||
| fw(title_string("Global Context", "-")) | fw(title_string("Global Context", "-")) | ||||
| fw("These properties are avilable in any contexts.\n\n") | fw("These properties are available in any contexts.\n\n") | ||||
| # very silly. could make these global and only access once. | # very silly. could make these global and only access once. | ||||
| # structs, funcs, ops, props = rna_info.BuildRNAInfo() | # structs, funcs, ops, props = rna_info.BuildRNAInfo() | ||||
| structs, funcs, ops, props = rna_info_BuildRNAInfo_cache() | structs, funcs, ops, props = rna_info_BuildRNAInfo_cache() | ||||
| struct = structs[("", "Context")] | struct = structs[("", "Context")] | ||||
| struct_blacklist = RNA_BLACKLIST.get(struct.identifier, ()) | struct_blacklist = RNA_BLACKLIST.get(struct.identifier, ()) | ||||
| del structs, funcs, ops, props | del structs, funcs, ops, props | ||||
| sorted_struct_properties = struct.properties[:] | sorted_struct_properties = struct.properties[:] | ||||
| sorted_struct_properties.sort(key=lambda prop: prop.identifier) | sorted_struct_properties.sort(key=lambda prop: prop.identifier) | ||||
| # First write RNA | # First write RNA | ||||
| for prop in sorted_struct_properties: | for prop in sorted_struct_properties: | ||||
| # support blacklisting props | # support blacklisting props | ||||
| if prop.identifier in struct_blacklist: | if prop.identifier in struct_blacklist: | ||||
| continue | continue | ||||
| type_descr = prop.get_type_description( | type_descr = prop.get_type_description( | ||||
| class_fmt=":class:`bpy.types.%s`", collection_id=_BPY_PROP_COLLECTION_ID) | 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) | ||||
| # special exception, cant use genric code here for enums | # special exception, can't use generic code here for enums | ||||
| if prop.type == "enum": | if prop.type == "enum": | ||||
| enum_text = pyrna_enum2sphinx(prop) | enum_text = pyrna_enum2sphinx(prop) | ||||
| if enum_text: | if enum_text: | ||||
| write_indented_lines(" ", fw, enum_text) | write_indented_lines(" ", fw, enum_text) | ||||
| fw("\n") | fw("\n") | ||||
| del enum_text | del enum_text | ||||
| # end enum exception | # end enum exception | ||||
| ▲ Show 20 Lines • Show All 105 Lines • ▼ Show 20 Lines | def write_param(ident, fw, prop, is_return=False): | ||||
| enum_text = pyrna_enum2sphinx(prop) | enum_text = pyrna_enum2sphinx(prop) | ||||
| if prop.name or prop.description or enum_text: | if prop.name or prop.description or enum_text: | ||||
| fw(ident + ":%s%s:\n\n" % (id_name, identifier)) | fw(ident + ":%s%s:\n\n" % (id_name, identifier)) | ||||
| if prop.name or prop.description: | if prop.name or prop.description: | ||||
| fw(ident + " " + ", ".join(val for val in (prop.name, prop.description) if val) + "\n\n") | fw(ident + " " + ", ".join(val for val in (prop.name, prop.description) if val) + "\n\n") | ||||
| # special exception, cant use genric code here for enums | # special exception, can't use generic code here for enums | ||||
| if enum_text: | if enum_text: | ||||
| write_indented_lines(ident + " ", fw, enum_text) | write_indented_lines(ident + " ", fw, enum_text) | ||||
| fw("\n") | fw("\n") | ||||
| del enum_text | del enum_text | ||||
| # end enum exception | # end enum exception | ||||
| fw(ident + ":%s%s: %s\n" % (id_type, identifier, type_descr)) | fw(ident + ":%s%s: %s\n" % (id_type, identifier, type_descr)) | ||||
| ▲ Show 20 Lines • Show All 82 Lines • ▼ Show 20 Lines | def write_struct(struct): | ||||
| # readonly properties use "data" directive, variables properties use "attribute" directive | # readonly properties use "data" directive, variables properties use "attribute" directive | ||||
| if 'readonly' in type_descr: | if 'readonly' in type_descr: | ||||
| fw(" .. data:: %s\n\n" % prop.identifier) | fw(" .. data:: %s\n\n" % prop.identifier) | ||||
| else: | else: | ||||
| fw(" .. attribute:: %s\n\n" % prop.identifier) | fw(" .. attribute:: %s\n\n" % prop.identifier) | ||||
| if prop.description: | if prop.description: | ||||
| fw(" %s\n\n" % prop.description) | fw(" %s\n\n" % prop.description) | ||||
| # special exception, cant use genric code here for enums | # special exception, can't use generic code here for enums | ||||
| if prop.type == "enum": | if prop.type == "enum": | ||||
| enum_text = pyrna_enum2sphinx(prop) | enum_text = pyrna_enum2sphinx(prop) | ||||
| if enum_text: | if enum_text: | ||||
| write_indented_lines(" ", fw, enum_text) | write_indented_lines(" ", fw, enum_text) | ||||
| fw("\n") | fw("\n") | ||||
| del enum_text | del enum_text | ||||
| # end enum exception | # end enum exception | ||||
| Show All 16 Lines | def write_struct(struct): | ||||
| for prop in func.args: | for prop in func.args: | ||||
| write_param(" ", fw, prop) | write_param(" ", fw, prop) | ||||
| if len(func.return_values) == 1: | if len(func.return_values) == 1: | ||||
| write_param(" ", fw, func.return_values[0], is_return=True) | write_param(" ", fw, func.return_values[0], is_return=True) | ||||
| 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 | # TODO, pyrna_enum2sphinx for multiple return values... actually don't | ||||
| # think we even use this but still!!! | # think we even use this but still!!! | ||||
| type_descr = prop.get_type_description( | type_descr = prop.get_type_description( | ||||
| as_ret=True, class_fmt=":class:`%s`", collection_id=_BPY_PROP_COLLECTION_ID) | 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 | ||||
| # In rare cases descr may be empty | # In rare cases descr may be empty | ||||
| fw(" `%s`, %s\n\n" % | fw(" `%s`, %s\n\n" % | ||||
| ▲ Show 20 Lines • Show All 817 Lines • Show Last 20 Lines | |||||