address review comments

CHANGES.rst

@@ -3,9 +3,7 @@
 
 - Improve documentation (part 1) [#483]
 
-- other
-^^^^^
-  - Replace ``pkg_resources`` with ``importlib.metadata``. [#478]
+- Replace ``pkg_resources`` with ``importlib.metadata``. [#478]
 
 0.19.0 (2023-09-15)
 -------------------

docs/gwcs/fits_analog.rst

@@ -1,4 +1,4 @@
-.. _fits_equivalent_example
+.. _fits_equivalent_example:
 
 FITS Equivalent WCS Example
 ===========================
@@ -27,7 +27,7 @@ a FITS imaging WCS without distortion, defined in this FITS imaging header::
   RADESYS = 'ICRS'                / Equatorial coordinate system
 
 
-The following imports are generally useful:
+For this example the following imports are needed:
 
   >>> import numpy as np
   >>> from astropy.modeling import models
@@ -87,15 +87,16 @@ This WCS pipeline has only one step - from ``detector`` to ``sky``:
   detector linear_transform
       icrs             None
 
-To convert a pixel (x, y) = (1, 2) to sky coordinates, call the WCS object as a function:
+Now we have a complete WCS object. The next example will use it to convert pixel
+coordinates(1, 2) to sky coordinates:
 
   >>> sky = wcsobj(1*u.pix, 2*u.pix, with_units=True)
   >>> print(sky)
   <SkyCoord (ICRS): (ra, dec) in deg
     (5.52515954, -72.05190935)>
 
-The :meth:`~gwcs.wcs.WCS.invert` method evaluates the :meth:`~gwcs.wcs.WCS.backward_transform`
-if available, otherwise applies an iterative method to calculate the reverse coordinates.
+The :meth:`~gwcs.wcs.WCS.invert` method evaluates the :meth:`~gwcs.wcs.WCS.backward_transform` to provide a mapping from sky coordinates to pixel coordinates 
+if available, otherwise it applies an iterative method to calculate the pixel coordinates.
 
   >>> wcsobj.invert(sky)
   (<Quantity 1. pix>, <Quantity 2. pix>)

docs/gwcs/ifu.rst

@@ -38,6 +38,8 @@ First, import the usual packages.
 
 Next, create the appropriate mapper object corresponding to the figure above:
 
+  >>> # Ignore the details of how this mask is constructed; they are using
+  >>> # array operations to generate the mask displayed for this example.
   >>> y, x = np.mgrid[:1000, :500]
   >>> fmask = (((-x + 0.01 * y + 0.00002 * y**2)/ 500) * 13 - 0.5) + 14
   >>> mask = fmask.astype(np.int8)

docs/index.rst

@@ -121,8 +121,6 @@ There are two ways to save the WCS to a file:
 
 - `Save a WCS object as a pure ASDF file`_
 
-- `Save a WCS object as an ASDF extension in a FITS file`_
-
 
 A step-by-step example of constructing an imaging GWCS object.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -171,7 +169,7 @@ default.
   >>> tangent_projection = models.Pix2Sky_TAN()
   >>> celestial_rotation = models.RotateNative2Celestial(30., 45., 180.)
 
-For the last transformation, the 3 arguments are, respectively:
+For the last transformation, the three arguments are, respectively:
 
 - Celestial longitude (i.e., RA) of the fiducial point (e.g., (0, 0) in the input 
   spherical coordinates). 
@@ -181,7 +179,7 @@ For the last transformation, the 3 arguments are, respectively:
   always corresponds to a value of 180.
 
 The more general case where the detector is not aligned with north, would have
-a rotation transform after the pixelship and pixelscale transformations to
+a rotation transform after the pixelshift and pixelscale transformations to
 align the detector coordinates with north up.
 
 The net transformation from pixel coordinates to celestial coordinates then