Adding glossary + refactor API reference display (#785)

* adding glossary + refactor API reference display

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* add ROI to glossary + better docstrings for queries

* fixes docs

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fixed docs warnings

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Luca Marconato <[email protected]>

.gitignore

@@ -17,7 +17,9 @@ __pycache__/
 /data/
 
 # docs
-/docs
+docs/_build
+!docs/api/.md
+docs/**/generated
 
 # IDEs
 /.idea/
@@ -29,8 +31,6 @@ __pycache__/
 # temp files
 temp/
 
-# rst generated from myst
-docs/generated
 
 # symlinks (luca) for extending the refactoring to satellite projects
 napari-spatialdata

docs/api.md

@@ -1,235 +1,17 @@
 # API
 
-```{eval-rst}
-.. module:: spatialdata
+```{toctree}
+:maxdepth: 1
+
+api/SpatialData.md
+api/io.md
+api/operations.md
+api/transformations.md
+api/transformations_utils.md
+api/datasets.md
+api/dataloader.md
+api/models.md
+api/models_utils.md
+api/testing.md
+api/data_formats.md
 ```
-
-## SpatialData
-
-The `SpatialData` class (follow the link to explore its methods).
-
-```{eval-rst}
-.. autosummary::
-    :toctree: generated
-
-    SpatialData
-```
-
-## Operations
-
-Operations on `SpatialData` objects.
-
-```{eval-rst}
-.. autosummary::
-    :toctree: generated
-
-    bounding_box_query
-    polygon_query
-    get_values
-    get_element_instances
-    get_extent
-    get_centroids
-    join_spatialelement_table
-    match_element_to_table
-    get_centroids
-    match_table_to_element
-    concatenate
-    transform
-    rasterize
-    rasterize_bins
-    rasterize_bins_link_table_to_labels
-    to_circles
-    to_polygons
-    aggregate
-    map_raster
-    relabel_sequential
-```
-
-### Operations Utilities
-
-```{eval-rst}
-.. autosummary::
-    :toctree: generated
-
-    unpad_raster
-    are_extents_equal
-    deepcopy
-    get_pyramid_levels
-```
-
-## Models
-
-The elements (building-blocks) that constitute `SpatialData`.
-
-```{eval-rst}
-.. currentmodule:: spatialdata.models
-
-.. autosummary::
-    :toctree: generated
-
-    Image2DModel
-    Image3DModel
-    Labels2DModel
-    Labels3DModel
-    ShapesModel
-    PointsModel
-    TableModel
-```
-
-### Models Utilities
-
-```{eval-rst}
-.. currentmodule:: spatialdata.models
-
-.. autosummary::
-    :toctree: generated
-
-    get_model
-    SpatialElement
-    get_axes_names
-    get_spatial_axes
-    points_geopandas_to_dask_dataframe
-    points_dask_dataframe_to_geopandas
-    get_channels
-    get_channel_names
-    set_channel_names
-    force_2d
-```
-
-## Transformations
-
-The transformations that can be defined between elements and coordinate systems in `SpatialData`.
-
-```{eval-rst}
-.. currentmodule:: spatialdata.transformations
-
-.. autosummary::
-    :toctree: generated
-
-    BaseTransformation
-    Identity
-    MapAxis
-    Translation
-    Scale
-    Affine
-    Sequence
-```
-
-### Transformations Utilities
-
-```{eval-rst}
-.. currentmodule:: spatialdata.transformations
-
-.. autosummary::
-    :toctree: generated
-
-    get_transformation
-    set_transformation
-    remove_transformation
-    get_transformation_between_coordinate_systems
-    get_transformation_between_landmarks
-    align_elements_using_landmarks
-    remove_transformations_to_coordinate_system
-```
-
-## DataLoader
-
-```{eval-rst}
-.. currentmodule:: spatialdata.dataloader
-
-.. autosummary::
-    :toctree: generated
-
-    ImageTilesDataset
-```
-
-## Input/Output
-
-```{eval-rst}
-.. currentmodule:: spatialdata
-
-.. autosummary::
-    :toctree: generated
-
-    read_zarr
-    save_transformations
-    get_dask_backing_files
-```
-
-## Testing utilities
-
-```{eval-rst}
-.. currentmodule:: spatialdata.testing
-
-.. autosummary::
-    :toctree: generated
-
-    assert_spatial_data_objects_are_identical
-    assert_elements_are_identical
-    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.
-These classes are useful to ensure backward compatibility whenever a major version change is introduced. We also provide pointers to the latest format.
-
-### Raster format
-
-```{eval-rst}
-.. currentmodule:: spatialdata._io.format
-
-.. autosummary::
-    :toctree: generated
-
-    CurrentRasterFormat
-    RasterFormatV01
-```
-
-### Shapes format
-
-```{eval-rst}
-.. autosummary::
-    :toctree: generated
-
-    CurrentShapesFormat
-    ShapesFormatV01
-    ShapesFormatV02
-```
-
-### Points format
-
-```{eval-rst}
-.. autosummary::
-    :toctree: generated
-
-    CurrentPointsFormat
-    PointsFormatV01
-```
-
-### Tables format
-
-```{eval-rst}
-.. autosummary::
-    :toctree: generated
-
-    CurrentTablesFormat
-    TablesFormatV01
-```
-

docs/api/SpatialData.md

@@ -0,0 +1,8 @@
+# SpatialData object
+
+```{eval-rst}
+.. currentmodule:: spatialdata
+
+.. autoclass:: SpatialData
+   :members:
+```

docs/api/data_formats.md

@@ -0,0 +1,36 @@
+# Data formats (advanced)
+
+The SpatialData format is defined as a set of versioned subclasses of `spatialdata._io.format.SpatialDataFormat`, one per type of element.
+These classes are useful to ensure backward compatibility whenever a major version change is introduced. We also provide pointers to the latest format.
+
+```{eval-rst}
+.. currentmodule:: spatialdata._io.format
+
+.. autoclass:: CurrentRasterFormat
+   :members:
+   :undoc-members:
+.. autoclass:: RasterFormatV01
+   :members:
+   :undoc-members:
+.. autoclass:: CurrentShapesFormat
+   :members:
+   :undoc-members:
+.. autoclass:: ShapesFormatV01
+   :members:
+   :undoc-members:
+.. autoclass:: ShapesFormatV02
+   :members:
+   :undoc-members:
+.. autoclass:: CurrentPointsFormat
+   :members:
+   :undoc-members:
+.. autoclass:: PointsFormatV01
+   :members:
+   :undoc-members:
+.. autoclass:: CurrentTablesFormat
+   :members:
+   :undoc-members:
+.. autoclass:: TablesFormatV01
+   :members:
+   :undoc-members:
+```

docs/api/dataloader.md

@@ -0,0 +1,8 @@
+# Data Loaders
+
+```{eval-rst}
+.. currentmodule:: spatialdata.dataloader
+
+.. autoclass:: ImageTilesDataset
+   :members:
+```

docs/api/datasets.md

@@ -0,0 +1,11 @@
+# Datasets
+
+Convenience small datasets
+
+```{eval-rst}
+.. currentmodule:: spatialdata.datasets
+
+.. autofunction:: blobs
+.. autofunction:: blobs_annotating_element
+.. autofunction:: raccoon
+```

docs/api/io.md

@@ -0,0 +1,11 @@
+# Input/Output
+
+To read the data from a specific technology (e.g., Xenium, MERSCOPE, ...), you can use any of the [spatialdata-io readers](https://spatialdata.scverse.org/projects/io/en/latest/api.html).
+
+```{eval-rst}
+.. currentmodule:: spatialdata
+
+.. autofunction:: read_zarr
+.. autofunction:: save_transformations
+.. autofunction:: get_dask_backing_files
+```

docs/api/models.md

@@ -0,0 +1,29 @@
+# Models
+
+The elements (building-blocks) that constitute `SpatialData`.
+
+```{eval-rst}
+.. currentmodule:: spatialdata.models
+
+.. autoclass:: Image2DModel
+   :members:
+   :undoc-members:
+.. autoclass:: Image3DModel
+   :members:
+   :undoc-members:
+.. autoclass:: Labels2DModel
+   :members:
+   :undoc-members:
+.. autoclass:: Labels3DModel
+   :members:
+   :undoc-members:
+.. autoclass:: ShapesModel
+   :members:
+   :undoc-members:
+.. autoclass:: PointsModel
+   :members:
+   :undoc-members:
+.. autoclass:: TableModel
+   :members:
+   :undoc-members:
+```

docs/api/models_utils.md

@@ -0,0 +1,15 @@
+# Models utils
+
+```{eval-rst}
+.. currentmodule:: spatialdata.models
+
+.. autofunction:: get_model
+.. autodata:: SpatialElement
+.. autofunction:: get_axes_names
+.. autofunction:: get_spatial_axes
+.. autofunction:: points_geopandas_to_dask_dataframe
+.. autofunction:: points_dask_dataframe_to_geopandas
+.. autofunction:: get_channel_names
+.. autofunction:: set_channel_names
+.. autofunction:: force_2d
+```