Read dev docs (#3685)

Author: MatthewPortman

docs/cubeviz/displaycubes.rst

@@ -61,7 +61,7 @@ Box Zoom and Linked Box Zoom
 
 .. seealso::
 
-    :ref:`Box Zoom and Linked Box Zoom in Imviz <imviz_box_zoom>`
+    :ref:`Box Zoom and Linked Box Zoom in Imviz <imviz-box-zoom>`
         Documentation on panning and zooming in Imviz.
 
 .. _cubeviz-pan-zoom:
@@ -71,19 +71,19 @@ Pan/Zoom and Linked Pan/Zoom
 
 .. seealso::
 
-    :ref:`Pan/Zoom and Linked Pan/Zoom in Imviz <imviz_pan_zoom>`
+    :ref:`Pan/Zoom and Linked Pan/Zoom in Imviz <imviz-pan-zoom>`
         Documentation on panning and zooming in Imviz.
 
 .. note:: Pan/Zoom API and click-to-center feature in Imviz is not yet available on Cubeviz.
 
-.. _cubeviz_defining_spatial_regions:
+.. _cubeviz-defining-spatial-regions:
 
 Defining Spatial Regions
 ========================
 
 .. seealso::
 
-    :ref:`Defining Spatial Regions <imviz_defining_spatial_regions>`
+    :ref:`Defining Spatial Regions <imviz-defining-spatial-regions>`
         Documentation on defining spatial regions in an image viewer.
 
 Spatial regions allow users to select subsets of the data array for
@@ -109,7 +109,7 @@ alt key (Alt key on Windows, Option key on Mac) while clicking on a spaxel creat
 that point instead of moving the previously created region.
 You can then compare spectra at different spaxels using the spectrum viewer.
 You can also use the subset modes that are explained in the
-:ref:`Spatial Regions <imviz_defining_spatial_regions>`
+:ref:`Spatial Regions <imviz-defining-spatial-regions>`
 section above in the same way you would with the other subset selection tools.
 
 Note that moving the cursor outside of the image viewer or deactivating the spectrum-at-spaxel tool

docs/cubeviz/export_data.rst

@@ -7,14 +7,14 @@ Exporting Data from Cubeviz
 After data have been manipulated or analyzed, it is possible to export
 those data back into your Jupyter notebook.
 
-.. _cubeviz_export_regions:
+.. _cubeviz-export-regions:
 
 Spatial and Spectral Regions
 ============================
 
 .. seealso::
 
-    :ref:`Export Spatial Regions <imviz_export>`
+    :ref:`Export Spatial Regions <imviz-export>`
         Documentation on how to export spatial regions.
 
 To extract all the subsets created in the viewers, call the Subset Tools plugin:
@@ -101,7 +101,7 @@ All mouseover information in the :ref:`markers plugin <markers-plugin>` can be e
 by calling :meth:`~jdaviz.core.template_mixin.TableMixin.export_table` (see :ref:`plugin-apis`).
 
 
-.. _cubeviz_export_photometry:
+.. _cubeviz-export-photometry:
 
 Aperture Photometry
 ===================
@@ -114,10 +114,10 @@ Cubeviz can export photometry output table like Imviz through the Aperture Photo
 
 .. seealso::
 
-    :ref:`Imviz Aperture Photometry <imviz_export_photometry>`
+    :ref:`Imviz Aperture Photometry <imviz-export-photometry>`
         Imviz documentation describing exporting of aperture photometry results in Jdaviz.
 
-In addition to the columns that :ref:`Imviz Aperture Photometry <imviz_export_photometry>` provides,
+In addition to the columns that :ref:`Imviz Aperture Photometry <imviz-export-photometry>` provides,
 the table from Cubeviz has an extra column after ``data_label`` entitled ``slice_wave`` that stores
 the wavelength value at the selected slice of the cube used for computation.
 If a 2D data (e.g., collapsed cube) is selected, the value will be NaN.

docs/cubeviz/plugins.rst

@@ -25,7 +25,7 @@ Metadata Viewer
 
 .. seealso::
 
-    :ref:`Metadata Viewer <imviz_metadata-viewer>`
+    :ref:`Metadata Viewer <imviz-metadata-viewer>`
         Documentation on using the metadata viewer.
 
 .. _cubeviz-plot-options:

docs/dev/infrastructure.rst

@@ -2,20 +2,22 @@
 Jdaviz Design and Infrastructure
 ********************************
 
+This section outlines the top-level structure of Jdaviz.
+
 .. note::
 
     At the time of writing, Jdaviz was still in heavy development.
     If you notice that this page has fallen behind, please
     `report an issue to the Jdaviz GitHub issues <https://github.com/spacetelescope/jdaviz/issues/new>`_.
 
-This section outlines the top-level structure of Jdaviz. At the highest level,
-Jdaviz layers different, sometimes changing technologies in the Jupyter platform
-to do its visualization, and therefore provides a framework for these technologies
-to work together. This document describes that framework, as well as the high-level
-sets of components needed for the Jdaviz use cases; it lists the layers of the Jdaviz
-framework in essentially the order in which they contact users in a typical
-visualization-heavy workflow. An overview of the layers is in this diagram,
-and each is described in more details below:
+At the highest level, Jdaviz uses different, sometimes changing technologies in
+the Jupyter platform to do its visualization, and therefore provides a framework
+for these technologies to work together. This document describes that framework,
+as well as the high-level sets of components needed for the Jdaviz use cases;
+it lists the layers of the Jdaviz framework in approximately the order in which
+a user would interact with them in a typical visualization-heavy workflow.
+The following diagram presents an overview of the framework's layers, with each being described
+in more detail below:
 
 .. figure:: jdaviz.svg
     :alt: Jdaviz design and infrastructure chart.
@@ -26,13 +28,19 @@ and each is described in more details below:
     visualization libraries involved. The bottom layer consists of low-level
     data analysis and I/O libraries.
 
+.. note::
+
+    In the diagram above, optional dependencies of Jdaviz have dotted lines.
+    Optional dependencies are only required for certain Jdaviz
+    workflows and are not explicitly installed by default when Jdaviz is installed.
+
 Jdaviz: Interfaces and Applications
 ===================================
 
 Interfaces
 ----------
 
-"Interfaces" are the tools the user is using to access the analysis tools.
+"Interfaces" are the tools employed by the user to access the analysis tools.
 The word "platform" might at first seem more applicable, but in this case
 all of the interfaces are using Jupyter as the platform, to ensure a
 consistent look-and-feel and a single platform for which to target the tools.
@@ -63,8 +71,8 @@ The target interfaces are:
   maximum flexibility in embedding.
 
 Each of these interfaces uses a common set of applications implemented in Python
-and leveraging ipywidgets_ as the communication layer between Python and the
-JavaScript-level layout, rendering, and interactivity libraries. Hence the following
+and leverages ipywidgets_ as the communication layer between Python and the
+JavaScript-level layout, rendering, and interactivity libraries. Hence, the following
 layers are primarily implemented in Python, but utilize tools like ipyvuetify_ and
 ipygoldenlayout_ to allow the Python code to interact with the JavaScript
 implementations at the interface level.
@@ -84,23 +92,27 @@ applications and individual widgets.
 
 Specific target applications include:
 
-* *Specviz*: A view into a single astronomical spectrum. It provides a UI to
+* :ref:`specviz`: A view into a single astronomical spectrum. It provides a UI to
   view the spectrum, as well as perform common scientific operations like marking
   spectral regions for further analysis (e.g., in a notebook), subtracting continua,
   measuring and fitting spectral lines, etc.
-* *Mosviz*: A view into many astronomical spectra, typically the output of a
+* :ref:`specviz2d`: A view into 2D spectral data. It offers similar capabilities to
+  *Specviz*, namely that it provides a UI to visualize 2D spectra,
+  and can perform the same scientific operations on data. In addition to these, Specviz2D
+  can also extract 1D spectra from a selected region of the 2D spectrum.
+* :ref:`mosviz`: A view into many astronomical spectra, typically the output of a
   multi-object spectrograph (e.g.,
   `JWST NIRSpec <https://jwst.nasa.gov/content/observatory/instruments/nirspec.html>`_).
-  It provides capabilities for individual spectra like Specviz, but for multiple spectra
+  It provides capabilities for individual spectra like *Specviz*, but for multiple spectra
   at a time along with additional contextual information like on-sky views of the
   spectrograph slit.
-* *Cubeviz*: A view of spectroscopic data cubes (e.g., from
+* :ref:`cubeviz`: A view of spectroscopic data cubes (e.g., from
   `JWST MIRI <https://jwst.nasa.gov/content/observatory/instruments/miri.html>`_),
   along with 1D spectra extracted from the cube. In addition to common visualization
   capabilities like viewing slices or averages in image or wavelength space,
-  the application will provide some standard manipulations like smoothing, moment maps,
-  parallelized line fitting, etc.
-* *Imviz*: An image-viewer for 2D images leveraging the same machinery as the other
+  the application also provides the ability to perform smoothing operations and
+  parallelized line fitting, as well as generate moment maps, etc.
+* :ref:`imviz`: An image-viewer for 2D images leveraging the same machinery as the other
   applications. While this application is not intended to encapsulate a complete
   range of astronomical imaging-based workflows, it enables quick-look style
   visualization of images in a way that is compatible with the rest of the Jdaviz framework.
@@ -123,9 +135,10 @@ also provides the interface for registering new functionality (both UI and data/
 via glue-core's registries.
 
 Note that most of the application engine implementation belongs in glue-jupyter_
-or glue-core, as it is not unique to Jdaviz (or even astronomy). However, Jdaviz has
-customized it for specific use cases, though some of the implementations might be moved
-upstream as Jdaviz matures, especially if they are useful beyond Jdaviz.
+or `glue-core <https://github.com/glue-viz/glue>`_, as it is not unique to Jdaviz
+(or even astronomy). However, Jdaviz has customized it for specific use cases,
+though some of the implementations might be moved upstream as Jdaviz matures,
+especially if they are useful beyond Jdaviz.
 
 Visualization: Component Widgets
 ================================
@@ -168,9 +181,9 @@ Known component widgets for the target applications include:
   and selection of specific rows (to then be highlighted in other viewers or interacted
   with in notebook/lab).
 
-In addition to the component widgets above, there are also *plugins* that go with
-them to provide the necessary user interactions. Each plugin is specialized to do one
-thing, e.g., a "model fitting" plugin to allow users to fit
+In addition to the component widgets above, there are also *plugins* (e.g. :ref:`imviz-plugins`)
+that go with them to provide the necessary user interactions. Each plugin is specialized to do one
+thing, e.g., a :ref:`"model fitting" <specviz-model-fitting>` plugin that allows users to fit
 :ref:`astropy models <astropy:astropy-modeling>` to spectra.
 
 Data Analysis and I/O Libraries
@@ -196,13 +209,6 @@ so the list and the diagram above do not fully cover all of Jdaviz's dependencie
 but are the primary "top-level" data analysis or I/O libraries that most users are likely
 to focus on to complement or extend their Jdaviz workflows.
 
-.. note::
-
-    In the diagram above, optional dependencies of Jdaviz have dotted lines.
-    Optional dependencies mean they are only required for certain Jdaviz
-    workflows and are not explicitly installed by default when you install Jdaviz.
-
-
 .. _ipywidgets: https://ipywidgets.readthedocs.io
 .. _ipyvuetify: https://github.com/mariobuikhuizen/ipyvuetify
 .. _ipygoldenlayout: https://github.com/nmearl/ipygoldenlayout

docs/dev/links.rst

@@ -6,8 +6,8 @@ Linking of datasets in glue
 
 .. note:: The ``glue`` documentation includes a page about
           `linking <http://docs.glueviz.org/en/stable/developer_guide/linking.html>`_ but
-          the present page should be considered a
-          more up-to-date guide with a focus on links useful to Jdaviz.
+          the present page is intended to provide a more focused description of the
+          the linking mechanisms used by Jdaviz.
 
 The 'why' of linking
 ====================
@@ -84,7 +84,7 @@ in another dataset.
 Linking by WCS
 ==============
 
-There are two main ways of linking by WCS, as follow.
+There are two main ways of linking by WCS, as follows.
 
 Using WCSLink (recommended)
 ---------------------------

docs/dev/release.rst

@@ -51,13 +51,13 @@ procedure.
 You can do a release from your fork directly without a clean code check-out.
 
 1. Ensure `CI on Actions for main <https://github.com/spacetelescope/jdaviz/actions/workflows/ci_workflows.yml?query=branch%3Amain>`_
-   and `RTD build for latest <https://readthedocs.org/projects/jdaviz/builds/>`_
+   and `readthedocs (RTD) build for latest <https://readthedocs.org/projects/jdaviz/builds/>`_
    are passing.
 
 2. Lock down the ``main`` branch of the repository by setting the
    `branch protection <https://github.com/spacetelescope/jdaviz/settings/branches>`_
-   rule for ``main`` to some high number required to merge, so that more PRs don't
-   get merged while you're releasing.
+   rule for ``main`` (note: only available to Jdaviz admins) to some high number
+   required to merge, so that more PRs don't get merged while you're releasing.
 
 3. Create a new local branch and make sure you have updated tags too. Note
    that the "x" here should actually be the letter "x", whereas the upper case "X"
@@ -93,8 +93,9 @@ You can do a release from your fork directly without a clean code check-out.
 
 7. Push the ``vX.Y.x`` branch to upstream.
    Make sure the CI passes. If any of the CI fails,
-   abandon this way. Stop here; do not continue! Otherwise,
-   go to the next step.
+   stop here; do not continue! Contact the maintainers
+   for information on how to proceed.
+   Otherwise, go to the next step.
 
 8. Go to `Releases on GitHub <https://github.com/spacetelescope/jdaviz/releases>`_
    and `create a new GitHub release <https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository>`_
@@ -244,7 +245,7 @@ You can do a release from your fork directly without a clean code check-out.
 
 17. Follow procedures for :ref:`release-milestones` and :ref:`release-labels`.
 
-18. For your own sanity unrelated to the release, grab the new tag for your fork:
+18. For your own sanity (unrelated to the release), grab the new tag for your fork:
 
 .. code-block:: bash
 
@@ -267,12 +268,12 @@ The procedure for a bugfix release is a little different from a feature release
 be releasing from an existing release branch, and will also need to do some
 cleanup on the ``main`` branch. In the following, X and Y refer to the minor release for
 which you're doing a bugfix release. For example, if you are releasing v3.5.2, replace all
-instances of ``vX.Y.x`` with ``v3.5.x``. 
+instances of ``vX.Y.x`` with ``v3.5.x``.
 
 1. Lock down the ``vX.Y.x`` branch of the repository by setting the
    `branch protection <https://github.com/spacetelescope/jdaviz/settings/branches>`_
-   rule for ``v*.x`` to some high number required to merge, so that more PRs don't
-   get merged while you're releasing.
+   rule for ``v*.x`` (note: only available to Jdaviz admins) to some high number required to merge,
+   so that more PRs don't get merged while you're releasing.
 
 2. Review the appropriate `Milestone <https://github.com/spacetelescope/jdaviz/milestones>`_
    to see which PRs should be released in this version, and double check that any open
@@ -299,7 +300,8 @@ instances of ``vX.Y.x`` with ``v3.5.x``.
 
 7. Push the ``vX.Y.x`` branch to upstream.
    Make sure the CI passes. If any of the CI fails,
-   abandon this way. Stop here; do not continue! Otherwise,
+   stop here; do not continue! Contact the maintainers for
+   information on how to proceed. Otherwise,
    go to the next step.
 
 8. Go to `Releases on GitHub <https://github.com/spacetelescope/jdaviz/releases>`_
@@ -368,7 +370,7 @@ instances of ``vX.Y.x`` with ``v3.5.x``.
 
 16. Follow procedures for :ref:`release-milestones`.
 
-17. For your own sanity unrelated to the release, grab the new tag for your fork::
+17. For your own sanity (unrelated to the release), grab the new tag for your fork::
 
      git fetch upstream --tags
 
@@ -381,13 +383,13 @@ Milestones bookkeeping
 
 1. Go to `Milestones <https://github.com/spacetelescope/jdaviz/milestones>`_.
 
-2. Create a new milestone for the next release and the next bugfix release, if
-   doing a feature release, or for just the next bugfix release if you just did
-   one. You do not need to fill in the description and due date fields.
+2. If you are doing a bugfix release, create a new milestone for the next bugfix release.
+   If you are doing a feature release, create a new milestone for **both**
+   feature and bugfix releases.
+   You do not need to fill in the description and due date fields.
 
-3. For the milestone of this release, if there are any open issues or pull requests
-   still milestoned to it, move their milestones to the next feature or bugfix
-   milestone as appropriate.
+3. If there are any open issues or pull requests still attached to the current release,
+   move their milestones to the next feature or bugfix milestone as appropriate.
 
 4. Make sure the milestone of this release ends up with "0 open" and then close it.
 

docs/dev/specviz_selection.rst

@@ -5,8 +5,9 @@ Specviz Selections
 This section explains the working theory behind the selection tool and was inspired by
 the the introduction of two methods to the Specviz helper:
 
-* ``specviz.get_spectra()``
-* ``specviz.get_spectral_regions()``
+* `~jdaviz.configs.specviz.helper.Specviz.get_spectra()`
+* `~jdaviz.configs.specviz.helper.Specviz.get_spectral_regions()` (deprecated as of v4.1 in favor of
+  `~jdaviz.configs.default.plugins.subset_tools.subset_tools.SubsetTools.get_regions()`)
 
 Data loaded in are imported into Jdaviz and immediately converted into a
 ``specutils.SpectralRegion`` object. These are a spectral analog to the Astropy ``regions``
@@ -18,6 +19,7 @@ This is defined by the underlying ``glue`` library upon which Jdaviz relies on a
 "glue subset." Thus throughout the software documentation, we will refer to these
 user defined ranges as "subsets." Effectively, the selection tool defines a mask that
 can be thought of as "definition" of which data is and is not included in the subset.
-Upon extraction via ``specviz.get_spectral_regions()``, the method will return a new
-``specutils.SpectralRegion`` object that applies that mask atop of the proper region
-(data) displayed, and realizes the subset the user defined in Jdaviz.
+Upon extraction via `~jdaviz.configs.default.plugins.subset_tools.subset_tools.SubsetTools.get_regions()`,
+the method will return a new ``specutils.SpectralRegion`` object that applies that
+mask atop of the proper region (data) displayed, and realizes the subset the user
+defined in Jdaviz.