Revamp survey functionality and improve error handling

docs/api/surveys.catalog_utils.rst

@@ -1,8 +1,9 @@
+.. _surveys_catalog_utils:
+
 frb.surveys.catalog_utils
 =========================
 
 .. automodule:: frb.surveys.catalog_utils
-
-.. note::
-   Member-level API expansion is intentionally omitted here to avoid
-   docutils parsing failures during docs builds.
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/surveys.first.rst

@@ -0,0 +1,9 @@
+.. _surveys_first:
+
+frb.surveys.heasarc
+===================
+
+.. automodule:: frb.surveys.heasarc
+   :members: FIRST_Survey
+   :undoc-members:
+   :show-inheritance:

docs/api/surveys.nvss.rst

@@ -0,0 +1,9 @@
+.. _surveys_nvss:
+
+frb.surveys.heasarc
+===================
+
+.. automodule:: frb.surveys.heasarc
+   :members: NVSS_Survey
+   :undoc-members:
+   :show-inheritance:

docs/api/surveys.rst

@@ -1,46 +1,102 @@
-frb.surveys - Survey Data Access
+.. _surveys:
+
+frb.surveys — Survey Data Access
 =================================
 
-.. automodule:: frb.surveys
-   :members:
-   :undoc-members:
-   :show-inheritance:
+The `frb.surveys` package provides a uniform interface for querying dozens of
+astronomical surveys and catalogs. It handles the backend complexity of
+accessing data from various archives (NOIRLab Data Lab, HEASARC, IRSA, MAST,
+SkyView) and returns standardized `astropy` objects.
+
+For a hands-on guide with detailed examples for every survey class, see the
+companion tutorial notebook:
+
+.. toctree::
+   :maxdepth: 1
+
+   ../nb/Surveys
+
+
+
+
+
+
 
-Overview
---------
+General Usage
+-------------
 
-Access and query photometric/spectroscopic survey data
-(PanSTARRS, SDSS, DECaLS, WISE, 2MASS, DES, DESI, GALEX, etc.).
+All survey classes are instantiated with a sky coordinate and a search radius.
+The primary methods are `get_catalog()` to retrieve a source catalog as an
+`astropy.table.Table` and `get_image()` to download a FITS image as an
+`astropy.io.fits.HDUList`.
 
-Submodules
-----------
+Here is a typical example using Pan-STARRS:
+
+.. code-block:: python
+
+   from astropy.coordinates import SkyCoord
+   from astropy import units as u
+   from frb.surveys.panstarrs import Pan_STARRS_Survey
+
+   # Define coordinate and search radius
+   coord = SkyCoord('J081240.68+320809.0', unit=(u.hourangle, u.deg))
+   radius = 10 * u.arcsec
+
+   # Instantiate the survey object
+   ps1 = Pan_STARRS_Survey(coord, radius)
+
+   # Get the source catalog
+   catalog = ps1.get_catalog()
+
+   # Get a FITS image cutout
+   image_hdu = ps1.get_image()
+
+
+Utility Modules
+---------------
+
+The package includes two key utility modules for survey-agnostic operations
+and catalog manipulation.
 
 .. toctree::
    :maxdepth: 1
 
-   surveys.dlsurvey
+   surveys.survey_utils
    surveys.catalog_utils
+
+
+Survey-Specific Submodules
+--------------------------
+
+The following modules contain the individual survey classes.
+
+.. toctree::
+   :maxdepth: 1
+
    surveys.sdss
    surveys.des
    surveys.decals
-   surveys.wise
+   surveys.delve
+   surveys.nsc
+   surveys.hsc
    surveys.panstarrs
-   surveys.twomass
+   surveys.wise
    surveys.vista
-   surveys.hsc
+   surveys.twomass
    surveys.galex
-   surveys.desi
-   surveys.delve
    surveys.euclid
+   surveys.first
+   surveys.nvss
+   surveys.wenss
+   surveys.desi
    surveys.nedlvs
-   surveys.nsc
    surveys.psrcat
    surveys.heasarc
+   surveys.dlsurvey
    surveys.images
    surveys.cluster_search
    surveys.surveycoord
    surveys.survey_io
-   surveys.survey_utils
    surveys.tns_util
    surveys.utils_crossmatching
    surveys.defs
@@ -49,5 +105,6 @@ Submodules
    ``frb.surveys.dlsurvey`` requires the optional dependency
    ``datalab-client`` for NOIRLab Data Lab access.
 
+
 .. note::
    ``frb.surveys.psrcat`` requires optional ``FRB-pulsars`` support.

docs/api/surveys.survey_utils.rst

@@ -1,8 +1,9 @@
+.. _surveys_survey_utils:
+
 frb.surveys.survey_utils
 ========================
 
 .. automodule:: frb.surveys.survey_utils
-
-.. note::
-   Member-level API expansion is intentionally omitted here to avoid
-   docutils errors from malformed legacy docstrings.
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/surveys.wenss.rst

@@ -0,0 +1,9 @@
+.. _surveys_wenss:
+
+frb.surveys.heasarc
+===================
+
+.. automodule:: frb.surveys.heasarc
+   :members: WENSS_Survey
+   :undoc-members:
+   :show-inheritance: