Merge pull request #324 from spacetelescope/release-0.9

Release 0.9

.travis.yml

@@ -35,7 +35,7 @@ matrix:
         # Check for Sphinx doc build errors
         - python: 3.7
           env: SETUP_CMD='build_sphinx'
-                CONDA_DEPENDENCIES='scipy matplotlib nbsphinx pandoc'
+                CONDA_DEPENDENCIES='scipy matplotlib nbsphinx pandoc sphinx-issues'
                 PIP_DEPENDENCIES='git+https://github.com/spacetelescope/poppy.git#egg=poppy jwxml git+https://github.com/spacetelescope/pysiaf.git#egg=pysiaf nbsphinx sphinx_rtd_theme stsci_rtd_theme sphinx-automodapi'
 
         # Try Astropy development version
@@ -83,7 +83,7 @@ install:
 
 before_script:
     # Get WebbPSF data files (just a subset of the full 250 MB!) and set up environment variable
-    - wget https://stsci.box.com/shared/static/qpmg4njgeb4jg3qikce7wg6rmk4n7vx2.gz -O /tmp/minimal-webbpsf-data.tar.gz
+    - wget https://stsci.box.com/shared/static/qcptcokkbx7fgi3c00w2732yezkxzb99.gz -O /tmp/minimal-webbpsf-data.tar.gz
     - tar -xzvf /tmp/minimal-webbpsf-data.tar.gz
     - export WEBBPSF_PATH=$PWD/webbpsf-data
 

docs/conf.py

@@ -71,6 +71,7 @@ def setup(app):
     'sphinx.ext.viewcode',
     'sphinx.ext.autosummary',
     'sphinx_automodapi.automodapi',
+    'sphinx_issues'
     ]
 numpydoc_show_class_members = False
 
@@ -98,6 +99,13 @@ def setup(app):
 
 # -- Project information ------------------------------------------------------
 
+# Github integration via sphinx-issues plugin
+# See https://github.com/sloria/sphinx-issues
+
+# Github repo
+issues_github_path = "spacetelescope/webbpsf"
+
+
 # This does not *have* to match the package name, but typically does
 project = setup_cfg['package_name']
 author = setup_cfg['author']

docs/gui.rst

@@ -1,9 +1,17 @@
 .. _gui:
 
 **********************************************
-Using WebbPSF via the Graphical User Interface
+(Deprecated)  Graphical User Interface
 **********************************************
 
+.. warning::
+
+   The GUI is deprecated, no longer actively developed, and not a priority for support. It is
+   not recommended for more than the most basic use cases. The functionality and the following 
+   documentation is maintained for the time being, but this will likely go away in the next 
+   major release.
+
+
 The WebbPSF GUI provides an easy interface to much, but not all, of the functionality of WebbPSF. (Many advanced settings in the class attributes and :py:attr:`~webbpsf.JWInstrument.options` structure for :py:class:`webbpsf.JWInstrument` are not exposed in the GUI. The programming API is also much better suited for scripting calculations.)
 
 .. attention:: 

docs/index.rst

@@ -18,57 +18,40 @@ WebbPSF is a Python package that computes simulated point spread functions (PSFs
    Sample PSFs for the filters in the WFIRST WFI.
 
 
-
-**What this software does:**
-
-* Uses OPD maps precomputed by detailed optical simulations of JWST and WFIRST, and in the case of JWST
-  based on instrument and telescope flight hardware cryo-vacuum test results.
-* For JWST, computes PSF images with requested properties for any of JWST's instruments. Supports imaging, coronagraphy, and most spectrographic modes with all of JWST's instruments. IFUs are yet to come.
-* For WFIRST, computes PSFs with the Wide Field Imager, based on recent GSFC optical models, including field- and wavelength-dependent aberrations. 
-  A preliminary version of the Coronagraph Instrument is also available.
-* Provides a suite of tools for quantifying PSF properties such as FWHM, Strehl ratio, etc.
-
-**What this software does NOT do:**
-
-* Contain in itself any detailed thermal or optical model of JWST or WFIRST. For the results of end-to-end integrated simulations of JWST, see for instance `Predicted JWST imaging performance (Knight, Lightsey, & Barto; Proc. SPIE 2012) <http://proceedings.spiedigitallibrary.org/proceeding.aspx?articleid=1362264>`_. For WFIRST modeling, see `the WFIRST Reference Info page <http://wfirst.gsfc.nasa.gov/science/Instrument_Reference_Information.html>`_
-* Model spectrally dispersed PSFs produced by any of the spectrograph gratings. It does, however, let you produce monochromatic PSFs in these modes, suitable for stitching together into spectra using some other software.
-* Model most detector effects such as pixel MTF, intrapixel sensitivity variations, interpixel capacitance, or any noise sources. Add those separately with your favorite detector model code. (\*Note, one particularly significant
-  detector scattering for MIRI imaging has now been added.)
-
 **Contributors:**
-WebbPSF has been developed by Marshall Perrin, Joseph Long, Shannon Osborne, Neil Zimmerman, Robel Geda,  Marcio Melendez Hernandez, Lauren Chambers, Keira Brooks, and Anand Sivaramakrishnan, with contributions from Jarron Leisenring, Ewan Douglas, Charles Lajoie, Megan Sosey, Kathryn St.Laurent, and the developers of  the astropy-helpers template framework.
+WebbPSF has been developed by Marshall Perrin, Joseph Long, Shannon Osborne, Robel Geda, Neil Zimmerman, Marcio Melendez Hernandez, Lauren Chambers, Keira Brooks, and Anand Sivaramakrishnan, with contributions from Jarron Leisenring, Ewan Douglas, Charles Lajoie, Megan Sosey, Kathryn St.Laurent, and the developers of  the astropy-helpers template framework.
 
 Getting Started with WebbPSF
 ----------------------------
 
-The WebbPSF software system is composed of two Python packages: a lower-level optical propagation library (:py:mod:`POPPY <poppy>`) plus an implementation of the JWST instruments using that library (:py:mod:`WebbPSF <webbpsf>`).  This documentation explains the programming interfaces and graphical user interface of WebbPSF, as well as providing a :ref:`quick overview <poppy_overiew>` of POPPY.
-
 .. admonition:: Quickstart Jupyter Notebook
 
    This documentation is complemented by an `Jupyter Notebook format quickstart tutorial <http://nbviewer.jupyter.org/github/spacetelescope/webbpsf/blob/master/notebooks/WebbPSF_tutorial.ipynb>`_. Downloading and running that notebook is a great way to get started using WebbPSF.
 
+.. note:: 
+   *Getting help:* For help using or installing webbpsf, you can contact the STScI Help Desk, help@stsci.edu. Note that WebbPSF is included in the Astroconda  python distribution, as well as being installable via :ref:`standard Python packaging tools <installation>`.
+
+
 :ref:`What's new in the latest release? <whatsnew>`
 
+Contents
+--------
 
 .. toctree::
    :maxdepth: 1
 
    intro.rst
    installation.rst
-   webbpsf.rst
+   relnotes.rst
+   usage.rst
    jwst.rst
    wfirst.rst
    psf_grids.rst
-   gui.rst
    more_examples.rst
    poppy.rst
 
-.. admonition:: Getting Help
-
-   For help using or installing webbpsf, you can contact the STScI Help Desk, help@stsci.edu. Note that WebbPSF is included in the Astroconda  python distribution, as well as being installable via :ref:`standard Python packaging tools <installation>`..
-
 Advanced Usage
---------------
+^^^^^^^^^^^^^^
 
 .. toctree::
    :maxdepth: 1
@@ -80,14 +63,14 @@ Advanced Usage
    fft_optimization.rst
 
 Appendices and Reference
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. toctree::
    :maxdepth: 1
 
-   relnotes.rst
    available_opds.rst
    references.rst
+   gui.rst
    release.rst
 
 

docs/installation.rst

@@ -3,10 +3,14 @@
 Requirements & Installation
 ===========================
 
-The latest released version of WebbPSF can be installed with the conda package management system or `using pip <install_pip>`_.
+.. note:: 
 
+   This is entirely optional, but you may wish to sign up to the mailing list ``webbpsf-users@maillist.stsci.edu``. This is a very low-traffic moderated announce-only list, to which we will periodically post announcements of updates to this software.
 
-Recommended best method: Installing via AstroConda
+   To subscribe, visit  the `maillist.stsci.edu server <https://maillist.stsci.edu/scripts/wa.exe?SUBED1=Webbpsf-users&A=1>`_
+
+
+Recommended: Installing via AstroConda
 --------------------------------------------------
 
 For ease of installation, we recommend using `AstroConda <http://astroconda.readthedocs.io/en/latest/>`_, an astronomy-optimized software distribution for scientific Python built on Anaconda. Install AstroConda according to `their instructions <http://astroconda.readthedocs.io/en/latest/installation.html>`_, then activate the environment with::
@@ -19,17 +23,15 @@ Next, install WebbPSF (along with all its dependencies and required reference da
 
    (astroconda)$ conda install webbpsf
 
+Updates to the latest version can be done as for any conda package::
 
-.. admonition:: Optional: sign up to receive announcement of updates
-
-   This is entirely optional, but you may wish to sign up to the mailing list ``webbpsf-users@stsci.edu``. This is a low-traffic moderated announce-only list, to which we will periodically post announcements of updates to this software.
+   (astroconda)$ conda update webbpsf
 
-   To subscribe, visit  the `maillist.stsci.edu server <https://maillist.stsci.edu/scripts/wa.exe?SUBED1=Webbpsf-users&A=1>`_
 
 .. _install-with-conda:
 
-Installing with conda (but no AstroConda)
------------------------------------------
+Installing with conda (but not AstroConda)
+-------------------------------------------
 
 If you already use ``conda``, but do not want to install the full suite of STScI software, you can simply add the AstroConda *channel* and install WebbPSF as follows (creating a new environment named ``webbpsf-env``)::
 
@@ -55,7 +57,7 @@ WebbPSF and its underlying optical library POPPY may be installed from the `Pyth
 
     Successfully installed webbpsf
 
-Note that ``pip install webbpsf`` only installs the program code. **If you install via pip, you must manually download and install the data files, as :ref:`described below <data_install>`.**
+Note that ``pip install webbpsf`` only installs the program code. **If you install via pip, you must manually download and install the data files, as :ref:`described <data_install>` below.**
 To obtain source spectra for calculations, you should also follow :ref:`installation instructions for pysynphot <pysynphot_install>`.
 
 
@@ -64,7 +66,7 @@ To obtain source spectra for calculations, you should also follow :ref:`installa
 Installing or updating pysynphot
 --------------------------------
 
-Pysynphot is an optional dependency, but is highly recommended.  Pysynphot is best installed via AstroConda. Further installation instructions can be found `here in the POPPY docs <http://poppy-optics.readthedocs.io/en/stable/installation.html#installing-or-updating-pysynphot>`_.
+Pysynphot is an optional dependency, but is highly recommended.  Pysynphot is best installed via AstroConda. Further installation instructions can be found in `the pysynphot docs <https://pysynphot.readthedocs.io/en/latest/#installation-and-setup>` or `a discussion in the POPPY docs <http://poppy-optics.readthedocs.io/en/stable/installation.html#installing-or-updating-pysynphot>`_.
 
 .. _data_install:
 
@@ -75,8 +77,8 @@ Installing the Required Data Files
 
 Files containing such information as the JWST pupil shape, instrument throughputs, and aperture positions are distributed separately from WebbPSF. To run WebbPSF, you must download these files and tell WebbPSF where to find them using the ``WEBBPSF_PATH`` environment variable.
 
-1. Download the following file:  `webbpsf-data-0.8.0.tar.gz <http://www.stsci.edu/~mperrin/software/webbpsf/webbpsf-data-0.8.0.tar.gz>`_  [approx. 240 MB]
-2. Untar ``webbpsf-data-0.8.0.tar.gz`` into a directory of your choosing.
+1. Download the following file:  `webbpsf-data-0.9.0.tar.gz <https://stsci.box.com/shared/static/qcptcokkbx7fgi3c00w2732yezkxzb99.gz>`_  [approx. 240 MB]
+2. Untar ``webbpsf-data-0.9.0.tar.gz`` into a directory of your choosing.
 3. Set the environment variable ``WEBBPSF_PATH`` to point to that directory. e.g. ::
 
    export WEBBPSF_PATH=$HOME/data/webbpsf-data
@@ -90,29 +92,28 @@ You should now be able to successfully ``import webbpsf`` in a Python session, o
    If you have previously installed the data files for an earlier version of WebbPSF, and then update to a newer version, the
    software may prompt you that you must download and install a new updated version of the data files.
 
-.. admonition:: For STScI Users Only
+.. Note:: 
 
-   Users at STScI may access the required data files from the Central Storage network. Set the following environment variables in your ``bash`` shell. (You will probably want to add this to your ``.bashrc``.) ::
+   **For STScI Users Only:** Users at STScI may access the required data files from the Central Storage network. Set the following environment variables in your ``bash`` shell. (You will probably want to add this to your ``.bashrc``.) ::
 
       export WEBBPSF_PATH="/grp/jwst/ote/webbpsf-data"
       export PYSYN_CDBS="/grp/hst/cdbs"
 
 Software Requirements
 ---------------------
 
-**Required Python version**: WebbPSF 0.8 and above require Python 3.5 or higher.
 
-**Required Python packages**:
+See `the environment.yml specification file <https://github.com/spacetelescope/webbpsf/blob/master/environment.yml>`_ for the required package dependencies. 
+
+**Required Python version**: WebbPSF 0.8 and above require Python 3.5 or higher.
 
-* Recent versions of `NumPy, SciPy <http://www.scipy.org/scipylib/download.html>`_ and `matplotlib <http://matplotlib.org>`_, if not installed already.
-* `Astropy <http://astropy.org>`_
-* `POPPY <https://pypi.python.org/pypi/poppy>`_
+The major dependencies are the standard `NumPy, SciPy <http://www.scipy.org/scipylib/download.html>`_, `matplotlib <http://matplotlib.org>`_ stack, and `Astropy <http://astropy.org>`_
 
 **Recommended Python packages**:
 
 * `pysynphot <https://pypi.python.org/pypi/pysynphot>`_ enables the simulation
   of PSFs with proper spectral response to realistic source spectra.  Without
-  this, PSF fidelity is reduced. See below for :ref:`installation instructions
+  this, PSF fidelity is reduced. See above for :ref:`installation instructions
   for pysynphot <pysynphot_install>`.  Pysynphot is recommended for most users.
 
 **Optional Python packages**:

docs/intro.rst

@@ -1,13 +1,28 @@
 Introduction
 ============
 
-Conceptually, this simulation code has three layers of abstraction:
+**What this software does:**
+
+* Uses OPD maps precomputed by detailed optical simulations of JWST and WFIRST, and in the case of JWST
+  based on instrument and telescope flight hardware cryo-vacuum test results.
+* For JWST, computes PSF images with requested properties for any of JWST's instruments. Supports imaging, coronagraphy, and most spectrographic modes with all of JWST's instruments. IFUs are yet to come.
+* For WFIRST, computes PSFs with the Wide Field Imager, based on recent GSFC optical models, including field- and wavelength-dependent aberrations. 
+  A preliminary version of the Coronagraph Instrument is also available.
+* Provides a suite of tools for quantifying PSF properties such as FWHM, Strehl ratio, etc.
+
+**What this software does NOT do:**
+
+* Contain in itself any detailed thermal or optical model of JWST or WFIRST. For the results of end-to-end integrated simulations of JWST, see for instance `Predicted JWST imaging performance (Knight, Lightsey, & Barto; Proc. SPIE 2012) <http://proceedings.spiedigitallibrary.org/proceeding.aspx?articleid=1362264>`_. For WFIRST modeling, see `the WFIRST Reference Info page <http://wfirst.gsfc.nasa.gov/science/Instrument_Reference_Information.html>`_
+* Model spectrally dispersed PSFs produced by any of the spectrograph gratings. It does, however, let you produce monochromatic PSFs in these modes, suitable for stitching together into spectra using some other software.
+* Model most detector effects such as pixel MTF, intrapixel sensitivity variations, interpixel capacitance, or any noise sources. Add those separately with your favorite detector model code. (\*Note, one particularly significant
+  detector scattering for MIRI imaging has now been added.)
+
+
+Conceptually, this simulation code has two layers of abstraction:
  * A base package for wavefront propagation through generic optical systems (provided by :py:mod:`POPPY <poppy>`)
- * Models of the JWST instruments implemented on top of that base system (provided by :py:mod:`WebbPSF <webbpsf>`)
- * An optional :ref:`graphical user interface <gui>`
+ * Models of the JWST and WFIRST instruments implemented on top of that base system (provided by :py:mod:`WebbPSF <webbpsf>`)
 
-It is entirely possible (and indeed recommended for scripting) to just use the :py:mod:`WebbPSF <webbpsf>` interface without the GUI, but the
-GUI can provide a quicker method for many simple interactive calculations.
+(There has formerly been a basic GUI front end, but that GUI is now deprecated and no longer recommended for use.)
 
 .. _intro_why_webbpsf:
 
@@ -105,27 +120,8 @@ For detailed installation instructions, refer to :ref:`installation`. (This docu
 
 Quick Start
 ------------
-First, download and install the software. Then just start ``python`` and
-
->>> import webbpsf
->>> webbpsf.gui()
-
-and you should be able to test drive things using the GUI:
-
-.. figure:: ./fig_gui_main.png
-   :scale: 75%
-   :align: center
-   :alt: The main window of the WebbPSF GUI when first launched.
-
-   The main window of the WebbPSF GUI when first launched.
-
-Most controls should be self-explanatory, so feel free to experiment. The article :ref:`gui` provides a detailed
-explanation of the GUI options. (Please note, the GUI only provides *basic* access to WebbPSF for introductory purposes; the Python programming interface is the recommended best way to use WebbPSF.)
-
-WebbPSF can save a detailed log of its calculations and results. This will by default be shown on screen but can also be saved to disk.
 
->>> webbpsf.setup_logging(filename='my_log_file.txt')
+Once you have installed the software and data files, we recommend you begin with the 
+`Jupyter Notebook quickstart tutorial <http://nbviewer.jupyter.org/github/spacetelescope/webbpsf/blob/master/notebooks/WebbPSF_tutorial.ipynb>`_. Downloading and running that notebook is a great way to get started using WebbPSF.
 
-Log settings are persistent between sessions, so you can just set this once the very first time you start WebbPSF and logging will be enabled thereafter until you explicitly change it.
 
-For further information, consult :ref:`using_api` or :ref:`gui`.

docs/release.rst

@@ -1,6 +1,6 @@
-**********************************
-Releasing a new version of WebbPSF
-**********************************
+***************************************************
+Developer Notes: Releasing a new version of WebbPSF
+***************************************************
 
 Prerequisites
 =============