Better docstring raster model (#716)

better docstring raster model, especially around rgba and c_coords

src/spatialdata/models/models.py

@@ -115,14 +115,21 @@ def parse(
             3D) labels. If you have a 2D image with shape yx, you can use :func:`numpy.expand_dims` (or an equivalent
             function) to add a channel dimension.
         dims
-            Dimensions of the data.
+            Dimensions of the data (e.g. ['c', 'y', 'x'] for 2D image data). If the data is a :class:`xarray.DataArray`,
+            the dimensions can also be inferred from the data. If the dimensions are not in the order (c)(z)yx, the data
+            will be transposed to match the order.
         transformations
-            Transformations to apply to the data.
+            Dictionary of transformations to apply to the data. The key is the name of the target coordinate system,
+            the value is the transformation to apply. By default, a single `Identity` transformation mapping to the
+            `"global"` coordinate system is applied.
         scale_factors
-            Scale factors to apply for multiscale.
-            If not None, a :class:`xarray.DataArray` is returned.
+            Scale factors to apply to construct a multiscale image (:class:`datatree.DataTree`).
+            If `None`, a :class:`xarray.DataArray` is returned instead.
+            Importantly, each scale factor is relative to the previous scale factor. For example, if the scale factors
+            are `[2, 2, 2]`, the returned multiscale image will have 4 scales. The original image and then the 2x, 4x
+            and 8x downsampled images.
         method
-            Method to use for multiscale.
+            Method to use for multiscale downsampling. Please refer to :class:`multiscale_spatial_image.to_multiscale`.
         chunks
             Chunks to use for dask array.
         kwargs
@@ -132,8 +139,18 @@ def parse(
 
         Returns
         -------
-        :class:`xarray.DataArray` or
-        :class:`datatree.DataTree`.
+        :class:`xarray.DataArray` or :class:`datatree.DataTree`
+
+        Notes
+        -----
+        **RGB images**
+
+        If you have an image with 3 or 4 channels and you want to interpret it as an RGB or RGB(A) image, you can use
+        the `c_coords` argument to specify the channel coordinates as `["r", "g", "b"]` or `["r", "g", "b", "a"]`.
+
+        You can also pass the `rgb` argument to `kwargs` to automatically set the `c_coords` to `["r", "g", "b"]`.
+        Please refer to :func:`to_spatial_image` for more information. Note: if you set `rgb=None` in `kwargs`, 3-4
+        channel images will be interpreted automatically as RGB(A) images.
         """
         if transformations:
             transformations = transformations.copy()