Doc: add bpy.utils.previews

Updated sphinx_doc_gen.py to better handle pure py-classes.

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))
+    doc = py_func.__doc__
-    if py_func.__doc__:
+    if (not doc) or (not doc.startswith(".. %s:: " % func_type)):
-        write_indented_lines(ident + "   ", fw, py_func.__doc__)
+        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",

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
+This allows scripts to generate their own previews, and use them as icons in UI widgets
-('icon_value' of UILayout functions).
+('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