Docs for datasets (blobs, raccoon) (#674)

docs/api.md

@@ -164,6 +164,22 @@ The transformations that can be defined between elements and coordinate systems
     assert_elements_dict_are_identical
 ```
 
+## Datasets
+
+Convenience small datasets
+
+```{eval-rst}
+.. currentmodule:: spatialdata.datasets
+
+.. autosummary::
+    :toctree: generated
+
+    blobs
+    blobs_annotating_element
+    raccoon
+
+```
+
 ## Data format (advanced topic)
 
 The SpatialData format is defined as a set of versioned subclasses of :class:`spatialdata._io.format.SpatialDataFormat`, one per type of element.
@@ -211,3 +227,4 @@ These classes are useful to ensure backward compatibility whenever a major versi
     CurrentTablesFormat
     TablesFormatV01
 ```
+

src/spatialdata/datasets.py

@@ -63,8 +63,7 @@ def blobs(
 
     Returns
     -------
-    SpatialData
-        SpatialData object with blobs dataset.
+    SpatialData object with blobs dataset.
     """
     return BlobsDataset(
         length=length,
@@ -355,6 +354,19 @@ def _generate_random_points(self, n: int, bbox: tuple[int, int]) -> list[Point]:
 
 
 def blobs_annotating_element(name: BlobsTypes) -> SpatialData:
+    """
+    Return the blobs dataset with the desired element annotated by the table.
+
+    Parameters
+    ----------
+    name
+        Name of the element to annotate. One of "blobs_labels", "blobs_multiscale_labels", "blobs_circles",
+        "blobs_polygons", "blobs_multipolygons".
+
+    Returns
+    -------
+    SpatialData object with the desired element annotated by the table.
+    """
     sdata = blobs(length=50)
     if name in ["blobs_labels", "blobs_multiscale_labels"]:
         instance_id = get_element_instances(sdata[name]).tolist()