Merge pull request #140 from tepickering/fix_doc_build

Enable nitpicky mode for sphinx and get docs to build cleanly

Author: tepickering

docs/conf.py

@@ -169,8 +169,14 @@
 
 # -- Turn on nitpicky mode for sphinx (to warn about references not found) ----
 #
-# nitpicky = True
-# nitpick_ignore = []
+nitpicky = True
+intersphinx_mapping.update(
+    {
+        'astropy': ('https://docs.astropy.org/en/stable/', None),
+        'ccdproc': ('https://ccdproc.readthedocs.io/en/stable/', None),
+        'specutils': ('https://specutils.readthedocs.io/en/stable/', None)
+    }
+)
 #
 # 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

docs/extinction.rst

@@ -11,7 +11,7 @@ and infrared.
 Supported Optical Extinction Models
 -----------------------------------
 
-`specreduce` offers support for average optical extinction models for a set of observatories:
+``specreduce`` offers support for average optical extinction models for a set of observatories:
 
 .. csv-table::
     :header:  "Model Name", "Observatory", "Lat", "Lon", "Elevation (m)", "Ref"
@@ -55,8 +55,8 @@ https://www.aanda.org/articles/aa/pdf/2011/03/aa15537-10.pdf.
 available at https://www.apo.nmsu.edu/arc35m/Instruments/DIS/ (https://www.apo.nmsu.edu/arc35m/Instruments/DIS/images/apoextinct.dat).
 
 In each case, the extinction is given in magnitudes per airmass and the wavelengths are in Angstroms. Here is an example that
-uses the `AtmosphericExtinction` class to load each model and plots the extinction in magnitudes as well as fractional transmission
-as a function of wavelength:
+uses the `~specreduce.calibration_data.AtmosphericExtinction` class to load each model and plots the extinction in magnitudes as well
+as fractional transmission as a function of wavelength:
 
 .. plot::
     :include-source:
@@ -76,9 +76,9 @@ as a function of wavelength:
     plt.tight_layout()
     fig.show()
 
-A convenience class, `AtmosphericTransmission`, is provided for loading data files containing atmospheric transmission versus wavelength.
-The common use case for this would be loading the output of telluric models. By default it loads a telluric model for an airmass of 1 and
-1 mm of precipitable water. Some resources for generating more realistic model atmospheric transmission spectra include
+A convenience class, `~specreduce.calibration_data.AtmosphericTransmission`, is provided for loading data files containing atmospheric transmission
+versus wavelength. The common use case for this would be loading the output of telluric models. By default it loads a telluric model for an
+airmass of 1 and 1 mm of precipitable water. Some resources for generating more realistic model atmospheric transmission spectra include
 https://mwvgroup.github.io/pwv_kpno/1.0.0/documentation/html/index.html and http://www.eso.org/sci/software/pipelines/skytools/molecfit.
 
 .. plot::

docs/index.rst

@@ -2,12 +2,12 @@
 Specreduce documentation
 ########################
 
-The `specreduce` package aims to provide a data reduction toolkit for optical
+The `specreduce <https://specreduce.readthedocs.io/en/latest/index.html>`_ package aims to provide a data reduction toolkit for optical
 and infrared spectroscopy, on which applications such as pipeline processes for
 specific instruments can be built. The scope of its functionality is limited to
 basic spectroscopic reduction, with basic *image* processing steps (such as
-bias subtraction) instead covered by `ccdproc` and other packages, data
-analysis by `specutils` and visualization by `specviz` or `cubeviz`. A few
+bias subtraction) instead covered by `ccdproc <https://ccdproc.readthedocs.io/en/latest/>`_ and other packages, data
+analysis by `specutils <https://specutils.readthedocs.io/en/latest/>`_ and visualization by `matplotlib <https://matplotlib.org/>`_. A few
 examples will nevertheless be provided of its usage in conjunction with these
 complementary packages.
 

docs/process/index.rst

@@ -6,7 +6,8 @@ Spectroscopic data reduction outline
 
 Here are some examples of complete DR processes, to help guide development
 (including basic image reduction steps, provided by other packages). These are
-not a summary of functionality actually implemented in `specreduce` today.
+not a summary of functionality actually implemented in
+`specreduce <https://specreduce.readthedocs.io/en/stable/index.html>`_ today.
 
 
 .. _specreduce-nir-mos:

docs/specphot_standards.rst

@@ -7,8 +7,8 @@ Introduction
 ------------
 
 Instrument sensitivity as a function of wavelength is calibrated using observations of
-spectrophotometric standard stars. `~specreduce` offers some convenience functions for accessing
-some databases of commonly used standard stars and loading the data into `~specutils.Spectrum1D`
+spectrophotometric standard stars. `specreduce <https://specreduce.readthedocs.io/en/stable/index.html>`_ offers some
+convenience functions for accessing some databases of commonly used standard stars and loading the data into `~specutils.Spectrum1D`
 instances.
 
 Supported Databases
@@ -18,8 +18,9 @@ Probably the most well-curated database of spectrophotometric calibration data i
 `CALSPEC <https://www.stsci.edu/hst/instrumentation/reference-data-for-calibration-and-tools/astronomical-catalogs/calspec>`_
 database at `MAST <https://archive.stsci.edu/>`_ (Ref.: `Bohlin, Gordon, & Tremblay 2014 <https://iopscience.iop.org/article/10.1086/677655>`_).
 It also has the advantage of including data that extends well into both the UV and the IR. The `~specreduce.calibration_data.load_MAST_calspec`
-function provides a way to easily load CALSPEC data either directly from `MAST` (specifically, https://archive.stsci.edu/hlsps/reference-atlases/cdbs/calspec/)
-or from a previously downloaded local file. Here is an example of how to use it and of a CALSPEC standard that has both UV and IR coverage:
+function provides a way to easily load CALSPEC data either directly from `MAST <https://archive.stsci.edu/>`_
+(specifically, https://archive.stsci.edu/hlsps/reference-atlases/cdbs/calspec/) or from a previously downloaded local file.
+Here is an example of how to use it and of a CALSPEC standard that has both UV and IR coverage:
 
 .. plot::
     :include-source:
@@ -38,91 +39,102 @@ or from a previously downloaded local file. Here is an example of how to use it
     fig.show()
 
 The `specreduce_data <https://github.com/astropy/specreduce-data/>`_ package provides several datasets of spectrophotometric standard spectra.
-The bulk of them are inherited from IRAF's `onedstds` datasets, but some more recently curated datasets from `ESO
-<https://www.eso.org/sci/observing/tools/standards/spectra/stanlis.html>`_, the
+The bulk of them are inherited from IRAF's `onedstds <https://github.com/iraf-community/iraf/tree/main/noao/lib/onedstds>`_ datasets, but
+some more recently curated datasets from `ESO <https://www.eso.org/sci/observing/tools/standards/spectra/stanlis.html>`_, the
 `Nearby Supernova Factory <https://snfactory.lbl.gov/>`_, and `Gemini
 <https://github.com/GeminiDRSoftware/DRAGONS/tree/master/geminidr/gemini/lookups/spectrophotometric_standards>`_ are included as well. The
 `~specreduce.calibration_data.load_onedstds` function is provided to load these data into `~specutils.Spectrum1D`
-instances. If `specreduce_data` is not installed, the data will be downloaded from the GitHub
+instances. If `specreduce_data <https://github.com/astropy/specreduce-data/>`_ is not installed, the data will be downloaded from the GitHub
 `repository <https://github.com/astropy/specreduce-data/tree/main/specreduce_data/reference_data/onedstds>`_. The available
 database names and their descriptions are listed here. Please refer to the `specreduce-data repository
 <https://github.com/astropy/specreduce-data/tree/main/specreduce_data/reference_data/onedstds>`_ for details on the
 specific data files that are available:
 
-- `bstdscal`: Directory of the brighter KPNO IRS standards (i.e. those with HR numbers) at 29 bandpasses,
-  data from various sources transformed to the Hayes and Latham system, unpublished.
+- `bstdscal <https://github.com/iraf-community/iraf/tree/main/noao/lib/onedstds/bstdscal>`_: Directory of the brighter KPNO IRS
+  standards (i.e., those with HR numbers) at 29 bandpasses, data from various sources transformed to the Hayes and Latham system, unpublished.
 
-- `ctiocal`: Directory containing fluxes for the southern tertiary standards as published by
+- `ctiocal <https://github.com/iraf-community/iraf/tree/main/noao/lib/onedstds/ctiocal>`_:
+  Directory containing fluxes for the southern tertiary standards as published by
   `Baldwin & Stone, 1984, MNRAS, 206, 241 <https://ui.adsabs.harvard.edu/abs/1984MNRAS.206..241B/abstract>`_
   and `Stone and Baldwin, 1983, MNRAS, 204, 347 <https://ui.adsabs.harvard.edu/abs/1983MNRAS.204..347S/abstract>`_.
 
-- `ctionewcal`: Directory containing fluxes at 50A steps in the blue range 3300-7550A for the
+- `ctionewcal <https://github.com/iraf-community/iraf/tree/main/noao/lib/onedstds/ctionewcal>`_:
+  Directory containing fluxes at 50 Å steps in the blue range 3300-7550 Å for the
   tertiary standards of Baldwin and Stone derived from the revised calibration of
   `Hamuy et al., 1992, PASP, 104, 533
   <https://ui.adsabs.harvard.edu/abs/1992PASP..104..533H/abstract>`_. This
-  directory also contains the fluxes of the tertiaries in the red (6050-10000A) at
-  50A steps as will be published in PASP (Hamuy et al 1994).  The combined fluxes
+  directory also contains the fluxes of the tertiaries in the red (6050-10000 Å) at
+  50 Å steps as will be published in PASP (Hamuy et al 1994).  The combined fluxes
   are obtained by gray shifting the blue fluxes to match the red fluxes in the
-  overlap region of 6500A-7500A and averaging the red and blue fluxes in the
+  overlap region of 6500-7500 Å and averaging the red and blue fluxes in the
   overlap.  The separate red and blue fluxes may be selected by following the star
   name with "red" or "blue"; i.e. CD 32 blue.
 
-- `iidscal`: Directory of the KPNO IIDS standards at 29 bandpasses,
+- `iidscal <https://github.com/iraf-community/iraf/tree/main/noao/lib/onedstds/iidscal>`_:
+  Directory of the KPNO IIDS standards at 29 bandpasses,
   data from various sources transformed to the Hayes and Latham
   system, unpublished.
 
-- `irscal`: Directory of the KPNO IRS standards at 78 bandpasses,
+- `irscal <https://github.com/iraf-community/iraf/tree/main/noao/lib/onedstds/irscal>`_:
+  Directory of the KPNO IRS standards at 78 bandpasses,
   data from various sources transformed to the Hayes and
   Latham system, unpublished (note that in this directory the
-  brighter standards have no values - the `bstdscal` directory
-  must be used for these standards).
+  brighter standards have no values - the `bstdscal <https://github.com/iraf-community/iraf/tree/main/noao/lib/onedstds/bstdscal>`_
+  directory must be used for these standards).
 
-- `oke1990`: Directory of spectrophotometric standards observed for use with the HST, Table
+- `oke1990 <https://github.com/iraf-community/iraf/tree/main/noao/lib/onedstds/oke1990>`_:
+  Directory of spectrophotometric standards observed for use with the HST, Table
   VII, `Oke 1990, AJ, 99, 1621
   <https://ui.adsabs.harvard.edu/abs/1990AJ.....99.1621O/abstract>`_ (no
-  correction was applied).  An arbitrary 1A bandpass is specified for these
+  correction was applied).  An arbitrary 1 Å bandpass is specified for these
   smoothed and interpolated flux "points".
 
-- `redcal`: Directory of standard stars with flux data beyond 8370A.
+- `redcal <https://github.com/iraf-community/iraf/tree/main/noao/lib/onedstds/redcal>`_:
+  Directory of standard stars with flux data beyond 8370 Å.
   These stars are from the IRS or the IIDS directory but
   have data extending as far out into the red as the
   literature permits.  Data from various sources.
 
-- `spechayescal`: The KPNO spectrophotometric standards at the Hayes flux
+- `spechayescal <https://github.com/iraf-community/iraf/tree/main/noao/lib/onedstds/spechayescal>`_:
+  The KPNO spectrophotometric standards at the Hayes flux
   points, Table IV, Spectrophotometric Standards, `Massey
   et al., 1988, ApJ 328, p. 315 <https://ui.adsabs.harvard.edu/abs/1988ApJ...328..315M/abstract>`_.
 
-- `spec16cal`: Directory containing fluxes at 16A steps in the blue
-  range 3300-7550A for the secondary standards, published in `Hamuy et al., 1992,
+- `spec16cal <https://github.com/iraf-community/iraf/tree/main/noao/lib/onedstds/spec16cal>`_:
+  Directory containing fluxes at 16 Å steps in the blue
+  range 3300-7550 Å for the secondary standards, published in `Hamuy et al., 1992,
   PASP, 104, 533
   <https://ui.adsabs.harvard.edu/abs/1992PASP..104..533H/abstract>`_.  This
-  directory also contains the fluxes of the secondaries in the red (6020-10300A)
-  at 16A steps as will be published in PASP (`Hamuy et al 1994
+  directory also contains the fluxes of the secondaries in the red (6020-10300 Å)
+  at 16 Å steps as will be published in PASP (`Hamuy et al 1994
   <https://ui.adsabs.harvard.edu/abs/1994PASP..106..566H/abstract>`_).  The
   combined fluxes are obtained by gray shifting the blue fluxes to match the red
-  fluxes in the overlap region of 6500A-7500A and averaging the blue and red
+  fluxes in the overlap region of 6500-7500 Å and averaging the blue and red
   fluxes in the overlap. The separate red and blue fluxes may be selected by
   following the star name with "red" or "blue"; i.e. HR 1544 blue.
 
-- `spec50cal`: The KPNO spectrophotometric standards at 50 A intervals. The data
+- `spec50cal <https://github.com/iraf-community/iraf/tree/main/noao/lib/onedstds/spec50cal>`_:
+  The KPNO spectrophotometric standards at 50 Å intervals. The data
   are from (1) Table V, Spectrophotometric Standards, `Massey et al., 1988, ApJ
   328, p. 315 <https://ui.adsabs.harvard.edu/abs/1988ApJ...328..315M/abstract>`_
   and (2) Table 3, The Kitt Peak Spectrophotometric Standards: Extension to 1
   micron, `Massey and Gronwall, 1990, ApJ 358, p. 344
   <https://ui.adsabs.harvard.edu/abs/1990ApJ...358..344M/abstract>`_.
 
-- `snfactory`: Preferred standard stars from the LBL Nearby Supernova Factory project:
+- `snfactory <https://snfactory.lbl.gov/>`_:
+  Preferred standard stars from the LBL Nearby Supernova Factory project:
   https://ui.adsabs.harvard.edu/abs/2002SPIE.4836...61A/abstract
   Data compiled from https://snfactory.lbl.gov/snf/snf-specstars.html.
   See notes there for details and references.
 
-- `eso`: Directories of spectrophotometric standards copied from
+- `eso`_:
+  Directories of spectrophotometric standards copied from
   ftp://ftp.eso.org/pub/stecf/standards/. See
   https://www.eso.org/sci/observing/tools/standards/spectra/stanlis.html
   for links, notes, and details.
 
-- `gemini`: Directory of spectrophotometric standards used by Gemini.
-  Originally copied from
+- `gemini <https://github.com/GeminiDRSoftware/DRAGONS/tree/master/geminidr/gemini/lookups/spectrophotometric_standards>`_:
+  Directory of spectrophotometric standards used by Gemini. Originally copied from
   https://github.com/GeminiDRSoftware/DRAGONS/tree/master/geminidr/gemini/lookups/spectrophotometric_standards.
 
 
@@ -133,7 +145,7 @@ Many commonly used standard stars have spectra in multiple datasets, but the qua
 The `~specreduce.calibration_data.load_MAST_calspec` and `~specreduce.calibration_data.load_onedstds` functions can be
 useful tools for exploring and comparing spectra from the various databases. An example is shown here for `LTT 9491
 <http://simbad.u-strasbg.fr/simbad/sim-id?Ident=LTT+9491&NbIdent=1&Radius=2&Radius.unit=arcmin&submit=submit+id>`_ which has
-spectra available from `MAST`, `ESO`, and the Nearby Supernova factory:
+spectra available from MAST, ESO, and the Nearby Supernova factory:
 
 .. plot::
     :include-source:
@@ -156,8 +168,9 @@ spectra available from `MAST`, `ESO`, and the Nearby Supernova factory:
     ax.legend()
     fig.show()
 
-The `MAST` data have the best UV coverage, but that's not useful from the ground and they only extend to 0.9 microns in the red in this case.
-The other data extend to 1.0 microns, but both spectra show systematics due to telluric absorption. The `SNFactory`
-data extend well past the atmospheric cutoff with no correction applied for atmospheric transmission. The `ESO` data, on the
-other hand, are not corrected for the telluric features in the near-IR while the `SNFactory` data are. Regions affected by
-such telluric systematics should be masked out before these spectra are used for calibration purposes.
+The `MAST`_ data have the best UV coverage, but that's not useful from the ground and
+they only extend to 0.9 microns in the red in this case. The other data extend to 1.0 microns, but both spectra show
+systematics due to telluric absorption. The `SNFactory`_ data extend well past the atmospheric
+cutoff with no correction applied for atmospheric transmission. The `ESO`_ data, on the other hand,
+are not corrected for the telluric features in the near-IR while the `SNFactory`_ data are.
+Regions affected by such telluric systematics should be masked out before these spectra are used for calibration purposes.