diff --git a/README.md b/README.md index dee5879..59bc9e6 100644 --- 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 index 14f0160..95c6a1f 100644 --- 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 index 2ddd2c1..b5a4585 100644 --- 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 index 1bc10d8..4f830e0 100644 --- 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 index c071f3d..129305a 100644 --- 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 `_; 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,8 +296,8 @@ 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". @@ -307,7 +305,7 @@ def set_catalog_style( ------ 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