Major docs update

README.rst

@@ -1,6 +1,10 @@
 Exposure time calculator for APO/ARCES
 --------------------------------------
 
+.. image:: https://readthedocs.org/projects/arcesetc/badge/?version=latest
+    :target: https://arcesetc.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+
 .. image:: http://img.shields.io/badge/powered%20by-AstroPy-orange.svg?style=flat
     :target: http://www.astropy.org
     :alt: Powered by Astropy Badge

arcesetc/plots.py

@@ -38,6 +38,9 @@ def plot_order_counts(sptype, wavelength, V, exp_time=None,
     kwargs : dict
         All extra keyword arguments will be passed to the plot function
 
+    .. warning ::
+        ``arcesetc`` doesn't know anything about saturation. Ye be warned!
+
     Returns
     -------
     fig : `~matplotlib.pyplot.Figure`
@@ -47,6 +50,34 @@ def plot_order_counts(sptype, wavelength, V, exp_time=None,
     exp_time : `~astropy.units.Quantity`
         Exposure time input, or computed to achieve S/N ratio
         ``signal_to_noise`` at wavelength ``wavelength``
+
+    Examples
+    --------
+
+    Given an exposure time:
+
+    >>> import matplotlib.pyplot as plt
+    >>> import astropy.units as u
+    >>> from arcesetc import plot_order_counts
+    >>> sptype = 'G4V'
+    >>> wavelength = 6562 * u.Angstrom
+    >>> exp_time = 30 * u.min
+    >>> V = 10
+    >>> fig, ax, exp_time = plot_order_counts(sptype, wavelength, V, exp_time=exp_time)
+    >>> plt.show()
+
+    ...or given a desired signal-to-noise ratio:
+
+    >>> import matplotlib.pyplot as plt
+    >>> import astropy.units as u
+    >>> from arcesetc import plot_order_counts
+    >>> sptype = 'G4V'
+    >>> wavelength = 6562 * u.Angstrom
+    >>> signal_to_noise = 30
+    >>> V = 10
+    >>> fig, ax, exp_time = plot_order_counts(sptype, wavelength, V, signal_to_noise=signal_to_noise)
+    >>> plt.show()
+
     """
     target, closest_spectral_type = closest_target(sptype)
 
@@ -90,6 +121,9 @@ def plot_order_sn(sptype, wavelength, V, exp_time=None, signal_to_noise=None,
     Either ``exp_time`` or ``signal_to_noise`` should be supplied to the
     function (but not both).
 
+    .. warning ::
+        ``arcesetc`` doesn't know anything about saturation. Ye be warned!
+
     Parameters
     ----------
     sptype : str
@@ -118,6 +152,33 @@ def plot_order_sn(sptype, wavelength, V, exp_time=None, signal_to_noise=None,
     exp_time : `~astropy.units.Quantity`
         Exposure time input, or computed to achieve S/N ratio
         ``signal_to_noise`` at wavelength ``wavelength``
+
+    Examples
+    --------
+
+    Given an exposure time:
+
+    >>> import matplotlib.pyplot as plt
+    >>> import astropy.units as u
+    >>> from arcesetc import plot_order_sn
+    >>> sptype = 'G4V'
+    >>> wavelength = 6562 * u.Angstrom
+    >>> exp_time = 30 * u.min
+    >>> V = 10
+    >>> fig, ax, exp_time = plot_order_sn(sptype, wavelength, V, exp_time=exp_time)
+    >>> plt.show()
+
+    ...or given a desired signal-to-noise ratio:
+
+    >>> import matplotlib.pyplot as plt
+    >>> import astropy.units as u
+    >>> from arcesetc import plot_order_sn
+    >>> sptype = 'G4V'
+    >>> wavelength = 6562 * u.Angstrom
+    >>> signal_to_noise = 30
+    >>> V = 10
+    >>> fig, ax, exp_time = plot_order_sn(sptype, wavelength, V, signal_to_noise=signal_to_noise)
+    >>> plt.show()
     """
     target, closest_spectral_type = closest_target(sptype)
 

arcesetc/utils.py

@@ -163,23 +163,42 @@ def signal_to_noise_to_exp_time(sptype, wavelength, V, signal_to_noise):
     ``signal_to_noise`` at wavelength ``wavelength`` for a star of spectral type
     ``sptype`` and V magnitude ``V``.
 
+    .. warning ::
+        ``arcesetc`` doesn't know anything about saturation. Ye be warned!
+
     Parameters
     ----------
     sptype : str
         Spectral type of the star. If
     wavelength : `~astropy.units.Quantity`
+        Wavelength of interest.
     V : float
         V magnitude of the target
     signal_to_noise : float
         If ``signal_to_noise`` is a float, compute the appropriate exposure time
         to generate the S/N curve that has S/N = ``signal_to_noise`` at
         wavelength ``wavelength``. Otherwise, generate S/N curve for
         exposure time ``exp_time``.
+
     Returns
     -------
     exp_time : `~astropy.units.Quantity`
         Exposure time input, or computed to achieve S/N ratio
         ``signal_to_noise`` at wavelength ``wavelength``
+
+    Examples
+    --------
+
+    How many seconds must one expose ARCES on a V=12 mag M0V star to get a S/N
+    of 30 at the wavelength of H-alpha?
+
+    >>> from arcesetc import signal_to_noise_to_exp_time
+    >>> sptype = 'M0V'
+    >>> wavelength = 6562 * u.Angstrom
+    >>> signal_to_noise = 30
+    >>> V = 12
+    >>> signal_to_noise_to_exp_time(sptype, wavelength, V, signal_to_noise)
+    642.11444 s
     """
     target, closest_spectral_type = closest_target(sptype)
 

docs/arcesetc/gettingstarted.rst

@@ -0,0 +1,136 @@
+Getting Started
+===============
+
+Exposure time to counts
+-----------------------
+
+Given an exposure time, spectral type, and V magnitude, what are the counts and
+signal-to-noise ratios we can collect using ARCES on the ARC 3.5 m Telescope at
+Apache Point Observatory?
+
+First, let's import the packages we'll use::
+
+    import matplotlib.pyplot as plt
+    import astropy.units as u
+
+    from arcesetc import plot_order_counts, plot_order_sn
+
+Then let's specify the properties of the observation that we're going to make::
+
+
+    sptype = 'G4V'
+    wavelength = 6562 * u.Angstrom
+    exp_time = 30 * u.min
+    V = 10
+
+Now let's make a plot of the number of counts we can expect in the order
+containing ``wavelength``, using `~arcesetc.plot_order_counts`::
+
+    fig, ax, exp_time = plot_order_counts(sptype, wavelength, V, exp_time=exp_time)
+    plt.show()
+
+
+.. plot::
+
+    import matplotlib.pyplot as plt
+    import astropy.units as u
+
+    from arcesetc import plot_order_counts, plot_order_sn
+
+    sptype = 'G4V'
+    wavelength = 6562 * u.Angstrom
+    exp_time = 30 * u.min
+    V = 10
+
+    fig, ax, exp_time = plot_order_counts(sptype, wavelength, V, exp_time=exp_time)
+    plt.show()
+
+Similarly, we can plot the signal-to-noise ratio using `~arcesetc.plot_order_sn`
+like so::
+
+    fig, ax, exp_time = plot_order_sn(sptype, wavelength, V, exp_time=exp_time)
+    plt.show()
+
+.. plot::
+
+    import matplotlib.pyplot as plt
+    import astropy.units as u
+
+    from arcesetc import plot_order_counts, plot_order_sn
+
+    sptype = 'G4V'
+    wavelength = 6562 * u.Angstrom
+    exp_time = 30 * u.min
+    V = 10
+
+    fig, ax, exp_time = plot_order_sn(sptype, wavelength, V, exp_time=exp_time)
+    plt.show()
+
+.. warning::
+
+    The spectral type output by the ``arcesetc`` package (``G5V``) isn't
+    exactly the same as the one we requested (``G4V``). That's because the
+    package is giving you the nearest spectral type available in the library of
+    spectra.
+
+
+Signal-to-noise to exposure time
+--------------------------------
+
+Given a S/N at a particular wavelength, what's the appropriate exposure time? We
+can find out by supplying the desired ``signal_to_noise``, and ``arcesetc`` will
+compute the exposure time for you::
+
+    sptype = 'B3V'
+    wavelength = 3990 * u.Angstrom
+    signal_to_noise = 100
+    V = 5
+
+    fig, ax, exp_time = plot_order_sn(sptype, wavelength, V, signal_to_noise=signal_to_noise)
+    plt.show()
+
+.. plot::
+
+    import matplotlib.pyplot as plt
+    import astropy.units as u
+
+    from arcesetc import plot_order_counts, plot_order_sn
+
+    sptype = 'B3V'
+    wavelength = 3990 * u.Angstrom
+    signal_to_noise = 100
+    V = 5
+
+    fig, ax, exp_time = plot_order_sn(sptype, wavelength, V, signal_to_noise=signal_to_noise)
+    plt.show()
+
+
+Wolf-Rayet Star
+---------------
+
+We presently have one non-main sequence star in the library, and it's a
+Wolf-Rayet star of spectral type ``WN8h``. You can see the funky effects of the
+strong emission lines on the S/N near H-alpha, for example::
+
+    sptype = 'WN8h'
+    wavelength = 6562 * u.Angstrom
+    signal_to_noise = 30
+    V = 14
+
+    fig, ax, exp_time = plot_order_sn(sptype, wavelength, V, signal_to_noise=signal_to_noise)
+    plt.show()
+
+.. plot::
+
+    import matplotlib.pyplot as plt
+    import astropy.units as u
+
+    from arcesetc import plot_order_counts, plot_order_sn
+
+    sptype = 'WN8h'
+    wavelength = 6562 * u.Angstrom
+    signal_to_noise = 30
+    V = 14
+
+    fig, ax, exp_time = plot_order_sn(sptype, wavelength, V, signal_to_noise=signal_to_noise)
+    plt.show()

docs/arcesetc/installation.rst

@@ -0,0 +1,11 @@
+Installing arcesetc
+===================
+
+You can install arcesetc from the source code by doing the following::
+
+    git clone https://github.com/bmorris3/arcesetc.git
+    cd arcesetc
+    python setup.py install
+
+If you have any trouble installing ``arcesetc``, feel free to post an issue
+on `GitHub <https://github.com/bmorris3/arcesetc/issues>`_.

docs/arcesetc/nextsteps.rst

@@ -0,0 +1,30 @@
+Next steps
+==========
+
+No plots, just exposure times
+-----------------------------
+
+You can also calculate the exposure time required to obtain a given S/N using
+the `~arcesetc.signal_to_noise_to_exp_time` function. For example - how many
+seconds must one expose ARCES on a V=12 mag M0V star to get a S/N of 30 at the
+wavelength of H-alpha::
+
+    from arcesetc import signal_to_noise_to_exp_time
+    sptype = 'M0V'
+    wavelength = 6562 * u.Angstrom
+    signal_to_noise = 30
+    V = 12
+    print(signal_to_noise_to_exp_time(sptype, wavelength, V, signal_to_noise))
+
+This returns ``642.11444 s``, a `~astropy.units.Quantity` object containing the
+required exposure time.
+
+Available spectral types
+------------------------
+
+You can see which spectral types are available with the
+`~arcesetc.available_sptypes` function.
+
+.. warning::
+    At present, the best coverage is for late-F through early-M type main
+    sequence stars.

docs/conf.py

@@ -108,8 +108,8 @@
 
 
 html_theme_options = {
-    'logotext1': 'arcesetc',  # white,  semi-bold
-    'logotext2': '',  # orange, light
+    'logotext1': 'arces',  # white,  semi-bold
+    'logotext2': 'etc',  # orange, light
     'logotext3': ':docs'   # white,  light
     }
 

docs/index.rst

@@ -1,16 +1,16 @@
-Documentation
-=============
+ARCES ETC Docs
+==============
 
-This is the documentation for arcesetc.
-Calculate S/N and exposure times for stellar spectroscopy with the ARC Echelle
-Spectrograph (ARCES) on the 3.5 m Telescope at Apache Point Observatory
+This is the documentation for ``arcesetc``. Calculate S/N and exposure times for
+stellar spectroscopy with the `ARC Echelle Spectrograph (ARCES)
+<https://www.apo.nmsu.edu/arc35m/Instruments/ARCES/>`_ on the
+`ARC 3.5 m Telescope <https://www.apo.nmsu.edu/arc35m/>`_ at
+`Apache Point Observatory <https://www.apo.nmsu.edu>`_.
 
 .. toctree::
   :maxdepth: 2
 
+  arcesetc/installation.rst
+  arcesetc/gettingstarted.rst
+  arcesetc/nextsteps.rst
   arcesetc/index.rst
-
-.. note:: The layout of this directory is simply a suggestion.  To follow
-          traditional practice, do *not* edit this page, but instead place
-          all documentation for the package inside ``arcesetc/``.
-          You can follow this practice or choose your own layout.