[Images] [6/N] Fix image dtype docs. (#1008)

This PR fixes the `DataType.image()` dtype docs in a few places.

.gitignore

@@ -32,4 +32,4 @@ log/
 
 
 # docs autogen
-/docs/source/api_docs/*/
+/docs/source/api_docs/doc_gen/

daft/__init__.py

@@ -77,7 +77,7 @@ class daft:
     from_ray_dataset,
 )
 from daft.dataframe import DataFrame
-from daft.datatype import DataType
+from daft.datatype import DataType, ImageMode
 from daft.expressions import col, lit
 from daft.io import from_glob_path, read_csv, read_json, read_parquet
 from daft.series import Series
@@ -98,6 +98,7 @@ class daft:
     "DataFrame",
     "col",
     "DataType",
+    "ImageMode",
     "lit",
     "Series",
     "register_viz_hook",

daft/daft.pyi

@@ -6,31 +6,45 @@ class ImageMode(Enum):
     Supported image modes for Daft's image type.
     """
 
-    # 8-bit grayscale
+    #: 8-bit grayscale
     L: int
-    # 8-bit grayscale + alpha
+
+    #: 8-bit grayscale + alpha
     LA: int
-    # 8-bit RGB
+
+    #: 8-bit RGB
     RGB: int
-    # 8-bit RGB + alpha
+
+    #: 8-bit RGB + alpha
     RGBA: int
-    # 16-bit grayscale
+
+    #: 16-bit grayscale
     L16: int
-    # 16-bit grayscale + alpha
+
+    #: 16-bit grayscale + alpha
     LA16: int
-    # 16-bit RGB
+
+    #: 16-bit RGB
     RGB16: int
-    # 16-bit RGB + alpha
+
+    #: 16-bit RGB + alpha
     RGBA16: int
-    # 32-bit floating RGB
+
+    #: 32-bit floating RGB
     RGB32F: int
-    # 32-bit floating RGB + alpha
+
+    #: 32-bit floating RGB + alpha
     RGBA32F: int
 
     @staticmethod
     def from_mode_string(mode: str) -> ImageMode:
         """
         Create an ImageMode from its string representation.
+
+        Args:
+            mode: String representation of the mode. This is the same as the enum
+                attribute name, e.g. ``ImageMode.from_mode_string("RGB")`` would
+                return ``ImageMode.RGB``.
         """
         ...
 

daft/datatype.py

@@ -176,6 +176,28 @@ def embedding(cls, name: str, dtype: DataType, size: int) -> DataType:
     def image(
         cls, mode: str | ImageMode | None = None, height: int | None = None, width: int | None = None
     ) -> DataType:
+        """Create an Image DataType: image arrays contain (height, width, channel) ndarrays of pixel values.
+
+        Each image in the array has an :class:`~daft.ImageMode`, which describes the pixel dtype (e.g. uint8) and
+        the number of image channels/bands and their logical interpretation (e.g. RGB).
+
+        If the height, width, and mode are the same for all images in the array, specifying them when constructing
+        this type is advised, since that will allow Daft to create a more optimized physical representation
+        of the image array.
+
+        If the height, width, or mode may vary across images in the array, leaving these fields unspecified when
+        creating this type will cause Daft to respresent this image array as a heterogeneous collection of images,
+        where each image can have a different mode, height, and width. This is much more flexible, but will result
+        in a less compact representation and may be make some operations less efficient.
+
+        Args:
+            mode: The mode of the image. By default, this is inferred from the underlying data.
+                If height and width are specified, the mode must also be specified.
+            height: The height of the image. By default, this is inferred from the underlying data.
+                Must be specified if the width is specified.
+            width: The width of the image. By default, this is inferred from the underlying data.
+                Must be specified if the width is specified.
+        """
         if isinstance(mode, str):
             mode = ImageMode.from_mode_string(mode)
         if height is not None and width is not None:

docs/source/api_docs/context.rst

@@ -8,7 +8,7 @@ Control the execution backend that Daft will run on by calling these functions o
 
 .. autosummary::
     :nosignatures:
-    :toctree: configuration_functions
+    :toctree: doc_gen/configuration_functions
 
     daft.context.set_runner_py
     daft.context.set_runner_ray

docs/source/api_docs/dataframe.rst

@@ -5,7 +5,7 @@ DataFrame
 
 .. autosummary::
     :nosignatures:
-    :toctree: dataframe_methods
+    :toctree: doc_gen/dataframe_methods
 
     DataFrame
 
@@ -26,7 +26,7 @@ Manipulating Columns
 
 .. autosummary::
     :nosignatures:
-    :toctree: dataframe_methods
+    :toctree: doc_gen/dataframe_methods
 
     daft.DataFrame.select
     daft.DataFrame.with_column
@@ -41,7 +41,7 @@ Filtering Rows
 
 .. autosummary::
     :nosignatures:
-    :toctree: dataframe_methods
+    :toctree: doc_gen/dataframe_methods
 
     daft.DataFrame.distinct
     daft.DataFrame.where
@@ -54,7 +54,7 @@ Reordering
 
 .. autosummary::
     :nosignatures:
-    :toctree: dataframe_methods
+    :toctree: doc_gen/dataframe_methods
 
     daft.DataFrame.sort
     daft.DataFrame.repartition
@@ -66,7 +66,7 @@ Combining
 
 .. autosummary::
     :nosignatures:
-    :toctree: dataframe_methods
+    :toctree: doc_gen/dataframe_methods
 
     daft.DataFrame.join
 
@@ -81,7 +81,7 @@ Aggregations
 
 .. autosummary::
     :nosignatures:
-    :toctree: dataframe_methods
+    :toctree: doc_gen/dataframe_methods
 
     daft.DataFrame.groupby
     daft.DataFrame.sum
@@ -102,7 +102,7 @@ Materialization
 
 .. autosummary::
     :nosignatures:
-    :toctree: dataframe_methods
+    :toctree: doc_gen/dataframe_methods
 
     daft.DataFrame.collect
 
@@ -113,7 +113,7 @@ Visualization
 
 .. autosummary::
     :nosignatures:
-    :toctree: dataframe_methods
+    :toctree: doc_gen/dataframe_methods
 
     daft.DataFrame.show
 
@@ -127,7 +127,7 @@ Writing Data
 
 .. autosummary::
     :nosignatures:
-    :toctree: dataframe_methods
+    :toctree: doc_gen/dataframe_methods
 
     daft.DataFrame.write_parquet
     daft.DataFrame.write_csv
@@ -139,7 +139,7 @@ Integrations
 
 .. autosummary::
     :nosignatures:
-    :toctree: dataframe_methods
+    :toctree: doc_gen/dataframe_methods
 
     daft.DataFrame.to_pandas
     daft.DataFrame.to_ray_dataset
@@ -150,7 +150,7 @@ Schema and Lineage
 
 .. autosummary::
     :nosignatures:
-    :toctree: dataframe_methods
+    :toctree: doc_gen/dataframe_methods
 
     daft.DataFrame.explain
     daft.DataFrame.schema

docs/source/api_docs/datatype.rst

@@ -5,7 +5,7 @@ DataTypes
 
 .. autosummary::
     :nosignatures:
-    :toctree: datatype_methods
+    :toctree: doc_gen/datatype_methods
 
     daft.DataType
 
@@ -30,7 +30,7 @@ Numeric
 
 .. autosummary::
     :nosignatures:
-    :toctree: datatype_methods
+    :toctree: doc_gen/datatype_methods
 
     daft.DataType.int8
     daft.DataType.int16
@@ -51,7 +51,7 @@ Logical
 
 .. autosummary::
     :nosignatures:
-    :toctree: datatype_methods
+    :toctree: doc_gen/datatype_methods
 
     daft.DataType.bool
 
@@ -63,7 +63,7 @@ Strings
 
 .. autosummary::
     :nosignatures:
-    :toctree: datatype_methods
+    :toctree: doc_gen/datatype_methods
 
     daft.DataType.binary
     daft.DataType.string
@@ -76,7 +76,7 @@ Temporal
 
 .. autosummary::
     :nosignatures:
-    :toctree: datatype_methods
+    :toctree: doc_gen/datatype_methods
 
     daft.DataType.date
 
@@ -88,7 +88,7 @@ Nested
 
 .. autosummary::
     :nosignatures:
-    :toctree: datatype_methods
+    :toctree: doc_gen/datatype_methods
 
     daft.DataType.list
     daft.DataType.fixed_size_list
@@ -100,7 +100,7 @@ Python
 
 .. autosummary::
     :nosignatures:
-    :toctree: datatype_methods
+    :toctree: doc_gen/datatype_methods
 
     daft.DataType.python
 
@@ -115,7 +115,7 @@ Machine Learning
 
 .. autosummary::
     :nosignatures:
-    :toctree: datatype_methods
+    :toctree: doc_gen/datatype_methods
 
     daft.DataType.embedding
 
@@ -124,15 +124,25 @@ Computer Vision
 
 .. autosummary::
     :nosignatures:
-    :toctree: datatype_methods
+    :toctree: doc_gen/datatype_methods
 
     daft.DataType.image
 
+.. autosummary::
+    :nosignatures:
+
+    ImageMode
+
 
 Miscellaneous
 ^^^^^^^^^^^^^
 .. autosummary::
     :nosignatures:
-    :toctree: datatype_methods
+    :toctree: doc_gen/datatype_methods
 
     daft.DataType.null
+
+.. toctree::
+    :hidden:
+
+    datatype_image_mode/daft.ImageMode

docs/source/api_docs/datatype_image_mode/daft.ImageMode.from_mode_string.rst

@@ -0,0 +1,6 @@
+daft.ImageMode.from\_mode\_string
+=================================
+
+.. currentmodule:: daft
+
+.. automethod:: ImageMode.from_mode_string

docs/source/api_docs/datatype_image_mode/daft.ImageMode.rst

@@ -0,0 +1,27 @@
+daft.ImageMode
+==============
+
+.. currentmodule:: daft
+
+.. autoclass:: ImageMode
+
+   .. autosummary::
+      :toctree:
+
+      ~ImageMode.from_mode_string
+
+   .. rubric:: Variants
+
+   .. autosummary::
+
+      ~ImageMode.L
+      ~ImageMode.LA
+      ~ImageMode.RGB
+      ~ImageMode.RGBA
+      ~ImageMode.L16
+      ~ImageMode.LA16
+      ~ImageMode.RGB16
+      ~ImageMode.RGBA16
+      ~ImageMode.RGB32F
+      ~ImageMode.RGBA32F
+