Merge pull request #67 from pllim/all-the-docs

mwcraig · web-flow · commit 6c512c9d708b · 2025-06-27T11:54:20.000-07:00
DOC: nitpicky, CI badge
diff --git a/README.md b/README.md
@@ -1,5 +1,6 @@
 # AIDA, the Astronomical Image Display API
 
 [![Documentation Status](https://readthedocs.org/projects/aida/badge/?version=latest)](https://aida.readthedocs.io/en/latest/?badge=latest)
+[![CI](https://github.com/astropy/astro-image-display-api/actions/workflows/run_tests.yml/badge.svg)](https://github.com/astropy/astro-image-display-api/actions/workflows/run_tests.yml)
 
 Also see: https://github.com/astropy/astrowidgets
diff --git a/docs/api.rst b/docs/api.rst
@@ -5,3 +5,6 @@ AID API
 
 .. automodapi:: astro_image_display_api.interface_definition
     :no-inheritance-diagram:
+
+.. automodapi:: astro_image_display_api.image_viewer_logic
+    :no-inheritance-diagram:
diff --git a/docs/conf.py b/docs/conf.py
@@ -124,7 +124,7 @@
 # A dictionary of values to pass into the template engine's context for all pages.
 html_context = {
     "default_mode": "dark",
-    "to_be_indexed": ["stable", "latest"],
+    "to_be_indexed": ["latest"],
     "is_development": dev,
     "github_user": "astropy",
     "github_repo": "astro-image-display-api",
@@ -183,8 +183,8 @@
 
 # -- Turn on nitpicky mode for sphinx (to warn about references not found) ----
 #
-# nitpicky = True
-# nitpick_ignore = []
+nitpicky = True
+nitpick_ignore = []
 #
 # Some warnings are impossible to suppress, and you can list specific references
 # that should be ignored in a nitpick-exceptions file which should be inside
diff --git a/src/astro_image_display_api/image_viewer_logic.py b/src/astro_image_display_api/image_viewer_logic.py
@@ -24,6 +24,7 @@
 
 from .interface_definition import ImageViewerInterface
 
+__all__ = ["ImageViewerLogic"]
 
 @dataclass
 class CatalogInfo:
@@ -298,7 +299,7 @@ def load_image(
 
         Parameters
         ----------
-        file : str or `astropy.io.fits.HDU`
+        file : str or array-like
             The FITS file to load. If a string, it can be a URL or a
             file path.
 
diff --git a/src/astro_image_display_api/interface_definition.py b/src/astro_image_display_api/interface_definition.py
@@ -29,13 +29,13 @@ def load_image(self, data: Any, image_label: str | None = None) -> None:
         """
         Load data into the viewer. At a minimum, this should allow a FITS file
         to be loaded. Viewers may allow additional data types to be loaded, such as
-        2D arrays or `astropy.nddata.NDData` objects.
+        2D arrays or `~astropy.nddata.NDData` objects.
 
         Parameters
         ----------
         data :
             The data to load. This can be a FITS file, a 2D array,
-            or an `astropy.nddata.NDData` object.
+            or an `~astropy.nddata.NDData` object.
 
         image_label : optional
             The label for the image.
@@ -70,12 +70,12 @@ def set_cuts(
         Raises
         ------
         TypeError
-            If the `cuts` parameter is not a tuple or an
+            If the ``cuts`` parameter is not a tuple or an
             `astropy.visualization.BaseInterval` object.
 
         ValueError
-            If the `image_label` is not provided when there are multiple images loaded,
-            or if the `image_label` does not correspond to a loaded image.
+            If the ``image_label`` is not provided when there are multiple images loaded,
+            or if the ``image_label`` does not correspond to a loaded image.
         """
         raise NotImplementedError
 
@@ -99,8 +99,8 @@ def get_cuts(self, image_label: str | None = None) -> BaseInterval:
         Raises
         ------
         ValueError
-            If the `image_label` is not provided when there are multiple images loaded,
-            or if the `image_label` does not correspond to a loaded image.
+            If the ``image_label`` is not provided when there are multiple images loaded,
+            or if the ``image_label`` does not correspond to a loaded image.
         """
         raise NotImplementedError
 
@@ -122,11 +122,11 @@ def set_stretch(self, stretch: BaseStretch, image_label: str | None = None) -> N
         Raises
         ------
         TypeError
-            If the `stretch` is not a valid `BaseStretch` object
+            If the ``stretch`` is not a valid `~astropy.visualization.BaseStretch` object.
 
         ValueError
-            if the `image_label` is not provided when there are multiple images loaded
-            or if the `image_label` does not correspond to a loaded image.
+            If the ``image_label`` is not provided when there are multiple images loaded
+            or if the ``image_label`` does not correspond to a loaded image.
         """
         raise NotImplementedError
 
@@ -158,7 +158,7 @@ def set_colormap(self, map_name: str, image_label: str | None = None) -> None:
         ----------
         map_name
             The name of the colormap to set. This should be a
-            valid colormap name from Matplotlib`_;
+            valid colormap name from `Matplotlib <https://matplotlib.org/stable/gallery/color/colormap_reference.html>`_;
             not all backends will support
             all colormaps, so the viewer should handle errors gracefully.
         image_label : optional
@@ -169,10 +169,8 @@ def set_colormap(self, map_name: str, image_label: str | None = None) -> None:
         Raises
         ------
         ValueError
-            If the `map_name` is not a valid colormap name or if the `image_label`
+            If the ``map_name`` is not a valid colormap name or if the ``image_label``
             is not provided when there are multiple images loaded.
-
-        .. _Matplotlib: https://matplotlib.org/stable/gallery/color/colormap_reference.html
         """
         raise NotImplementedError
 
@@ -196,8 +194,8 @@ def get_colormap(self, image_label: str | None = None) -> str:
         Raises
         ------
         ValueError
-            If the `image_label` is not provided when there are multiple images loaded
-            or if the `image_label` does not correspond to a loaded image.
+            If the ``image_label`` is not provided when there are multiple images loaded
+            or if the ``image_label`` does not correspond to a loaded image.
         """
         raise NotImplementedError
 
@@ -220,7 +218,7 @@ def save(self, filename: str | os.PathLike, overwrite: bool = False) -> None:
         Raises
         ------
         FileExistsError
-            If the file already exists and `overwrite` is `False`.
+            If the file already exists and ``overwrite`` is `False`.
         """
         raise NotImplementedError
 
@@ -258,16 +256,16 @@ def load_catalog(
         catalog_label : str, optional
             The name of the marker set to use. If not given, a unique
             name will be generated.
-        catalog_style: dict, optional
+        catalog_style : dict, optional
             A dictionary that specifies the style of the markers used to
-            represent the catalog. See `ImageViewerInterface.set_catalog_style`
+            represent the catalog. See `~astro_image_display_api.interface_definition.ImageViewerInterface.set_catalog_style`
             for details.
 
         Raises
         ------
         ValueError
-            If the `table` does not contain the required columns, or if
-            the `catalog_label` is not provided when there are multiple
+            If the ``table`` does not contain the required columns, or if
+            the ``catalog_label`` is not provided when there are multiple
             catalogs loaded.
         """
         raise NotImplementedError
@@ -288,7 +286,7 @@ def set_catalog_style(
         ----------
         shape : str, optional
             The shape of the markers. Default is ``'circle'``. The set of
-            supported shapes is listed below in the `Notes` section.
+            supported shapes is listed below in the *Note* section below.
         color : str, optional
             The color of the markers. Default is ``'red'``. Permitted colors are
             any CSS4 color name. CSS4 also permits hex RGB or RGBA colors.
@@ -298,16 +296,16 @@ def set_catalog_style(
         **kwargs
             Additional keyword arguments to pass to the marker style.
 
-        Notes
-        -----
+        Note
+        ----
         The following shapes are supported: "circle", "square", "crosshair", "plus",
         "diamond".
 
         Raises
         ------
         ValueError
             If there are multiple catalog styles set and the user has not
-            specified a `catalog_label` for which to set the style, or if
+            specified a ``catalog_label`` for which to set the style, or if
             an style is set for a catalog that does not exist.
         """
         raise NotImplementedError
@@ -336,7 +334,7 @@ def get_catalog_style(self, catalog_label: str | None = None) -> dict:
 
         ValueError
             If there are multiple catalog styles set and the user has not
-            specified a `catalog_label` for which to get the style.
+            specified a ``catalog_label`` for which to get the style.
 
         """
         raise NotImplementedError
@@ -356,12 +354,12 @@ def remove_catalog(self, catalog_label: str | None = None) -> None:
         Raises
         ------
         ValueError
-            If the `catalog_label` is not provided when there are multiple
-            catalogs loaded, or if the `catalog_label` does not correspond to a
+            If the ``catalog_label`` is not provided when there are multiple
+            catalogs loaded, or if the ``catalog_label`` does not correspond to a
             loaded catalog.
 
         TypeError
-            If the `catalog_label` is not a string or `None`, or if it is not
+            If the ``catalog_label`` is not a string or `None`, or if it is not
             one of the allowed values.
         """
         raise NotImplementedError
@@ -400,7 +398,7 @@ def get_catalog(
         Raises
         ------
         ValueError
-            If the `catalog_label` is not provided when there are multiple catalogs
+            If the ``catalog_label`` is not provided when there are multiple catalogs
             loaded.
         """
         raise NotImplementedError
@@ -446,15 +444,15 @@ def set_viewport(
         Raises
         ------
         TypeError
-            If the `center` is not a `SkyCoord` object or a tuple of floats, or if
-            the `fov` is not a angular `Quantity` or a float, or if there is no WCS
+            If the ``center`` is not a `~astropy.coordinates.SkyCoord` object or a tuple of floats, or if
+            the ``fov`` is not a angular `~astropy.units.Quantity` or a float, or if there is no WCS
             and the center or field of view require a WCS to be applied.
 
         ValueError
-            If `image_label` is not provided when there are multiple images loaded.
+            If ``image_label`` is not provided when there are multiple images loaded.
 
         `astropy.units.UnitTypeError`
-            If the `fov` is a `Quantity` but does not have an angular unit.
+            If the ``fov`` is a `~astropy.units.Quantity` but does not have an angular unit.
         """
         raise NotImplementedError
 
@@ -468,9 +466,9 @@ def get_viewport(
         Parameters
         ----------
         sky_or_pixel : str, optional
-            If 'sky', the center will be returned as a `SkyCoord` object.
+            If 'sky', the center will be returned as a `~astropy.coordinates.SkyCoord` object.
             If 'pixel', the center will be returned as a tuple of pixel coordinates.
-            If `None`, the default behavior is to return the center as a `SkyCoord` if
+            If `None`, the default behavior is to return the center as a `~astropy.coordinates.SkyCoord` if
             possible, or as a tuple of floats if the image is in pixel coordinates and
             has no WCS information.
         image_label : str, optional
@@ -483,15 +481,15 @@ def get_viewport(
         dict
             A dictionary containing the current viewport settings.
             The keys are 'center', 'fov', and 'image_label'.
-            - 'center' is an `astropy.coordinates.SkyCoord` object or a tuple of floats.
-            - 'fov' is an `astropy.units.Quantity` object or a float.
+            - 'center' is an `~astropy.coordinates.SkyCoord` object or a tuple of floats.
+            - 'fov' is an `~astropy.units.Quantity` object or a float.
             - 'image_label' is a string representing the label of the image.
 
         Raises
         ------
         ValueError
-            If the `sky_or_pixel` parameter is not one of 'sky', 'pixel', or `None`,
-            or if the `image_label` is not provided when there are multiple images
-            loaded, or if the `image_label` does not correspond to a loaded image.
+            If the ``sky_or_pixel`` parameter is not one of 'sky', 'pixel', or `None`,
+            or if the ``image_label`` is not provided when there are multiple images
+            loaded, or if the ``image_label`` does not correspond to a loaded image.
         """
         raise NotImplementedError
