diff options
| -rw-r--r-- | doc/python_api/sphinx_doc_gen.py | 22 | ||||
| -rw-r--r-- | release/scripts/modules/bpy/utils/previews.py | 42 |
2 files changed, 49 insertions, 15 deletions
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index a49378f2f0e..72ddf251946 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -257,6 +257,7 @@ else: "bpy.props", "bpy.types", # supports filtering "bpy.utils", + "bpy.utils.previews", "bpy_extras", "gpu", "mathutils", @@ -642,10 +643,17 @@ def pyfunc2sphinx(ident, fw, module_name, type_name, identifier, py_func, is_cla else: func_type = "staticmethod" - fw(ident + ".. %s:: %s%s\n\n" % (func_type, identifier, arg_str)) - if py_func.__doc__: - write_indented_lines(ident + " ", fw, py_func.__doc__) + doc = py_func.__doc__ + if (not doc) or (not doc.startswith(".. %s:: " % func_type)): + fw(ident + ".. %s:: %s%s\n\n" % (func_type, identifier, arg_str)) + ident_temp = ident + " " + else: + ident_temp = ident + + if doc: + write_indented_lines(ident_temp, fw, doc) fw("\n") + del doc, ident_temp if is_class: write_example_ref(ident + " ", fw, module_name + "." + type_name + "." + identifier) @@ -916,7 +924,7 @@ def pymodule2sphinx(basepath, module_name, module, title): fw(value.__doc__) else: fw(".. class:: %s\n\n" % type_name) - write_indented_lines(" ", fw, value.__doc__, False) + write_indented_lines(" ", fw, value.__doc__, True) else: fw(".. class:: %s\n\n" % type_name) fw("\n") @@ -929,6 +937,11 @@ 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 + for key, descr in descr_items: + if type(descr) == types.FunctionType: + pyfunc2sphinx(" ", fw, module_name, type_name, key, descr, is_class=True) + for key, descr in descr_items: if type(descr) == MethodDescriptorType: py_descr2sphinx(" ", fw, descr, module_name, type_name, key) @@ -1608,6 +1621,7 @@ def write_rst_contents(basepath): # py modules "bpy.utils", + "bpy.utils.previews", "bpy.path", "bpy.app", "bpy.app.handlers", diff --git a/release/scripts/modules/bpy/utils/previews.py b/release/scripts/modules/bpy/utils/previews.py index 4e8adf8e209..9e407d619f1 100644 --- a/release/scripts/modules/bpy/utils/previews.py +++ b/release/scripts/modules/bpy/utils/previews.py @@ -23,13 +23,20 @@ This module contains utility functions to handle custom previews. It behaves as a high-level 'cached' previews manager. -This allows addons to generate their own previews, and use them as icons in UI widgets -('icon_value' of UILayout functions). +This allows scripts to generate their own previews, and use them as icons in UI widgets +('icon_value' for UILayout functions). + + +Custom Icon Example +------------------- + +.. literalinclude:: ../../../release/scripts/templates_py/ui_previews_custom_icon.py """ __all__ = ( "new", "remove", + "ImagePreviewCollection", ) import _bpy @@ -42,14 +49,21 @@ _uuid_open = set() # High-level previews manager. # not accessed directly -class _BPyImagePreviewCollection(dict): +class ImagePreviewCollection(dict): """ - Dict-like class of previews. + Dictionary-like class of previews. + + This is a subclass of Python's built-in dict type, + used to store multiple image previews. + + .. note:: + + - instance with :mod:`bpy.utils.previews.new` + - keys must be ``str`` type. + - values will be :class:`bpy.types.ImagePreview` """ # Internal notes: - # - keys in the dict are stored by name - # - values are instances of bpy.types.ImagePreview # - Blender's internal 'PreviewImage' struct uses 'self._uuid' prefix. def __init__(self): @@ -93,11 +107,13 @@ class _BPyImagePreviewCollection(dict): release.__doc__ = _utils_previews.release.__doc__ def clear(self): + """Clear all previews.""" for name in self.keys(): _utils_previews.release(self._gen_key(name)) super().clear() def close(self): + """Close the collection and clear all previews.""" self.clear() _uuid_open.remove(self._uuid) @@ -114,24 +130,28 @@ class _BPyImagePreviewCollection(dict): def new(): """ - Return a new preview collection. + :return: a new preview collection. + :rtype: :class:`ImagePreviewCollection` """ - return _BPyImagePreviewCollection() + return ImagePreviewCollection() -def remove(p): +def remove(pcoll): """ Remove the specified previews collection. + + :arg pcoll: Preview collection to close. + :type pcoll: :class:`ImagePreviewCollection` """ - p.close() + pcoll.close() # don't complain about resources on exit (only unregister) import atexit def exit_clear_warning(): - del _BPyImagePreviewCollection.__del__ + del ImagePreviewCollection.__del__ atexit.register(exit_clear_warning) del atexit, exit_clear_warning |