Docs updates for 0.8.0 (spacetelescope#258)

* refresh install docs

* Docs update, 0.8.0 release candidate 1

* Update docs/index.rst

Co-Authored-By: mperrin and shanosborne

README.rst

@@ -26,7 +26,7 @@ WebbPSF also supports simulating PSFs for the upcoming Wide Field Infrared Surve
 including its Wide Field Instrument and a preliminary version of the Coronagraph Instrument.
 
 Developed by Marshall Perrin, Joseph Long, Neil Zimmerman, Robel Geda, Shannon
-Osborne, Marcio Melendez Hernandez, and collaborators, 2010-2018.
+Osborne, Marcio Melendez Hernandez, Lauren Chambers, Keira Brooks, and collaborators, 2010-2018.
 
 Documentation can be found online at https://webbpsf.readthedocs.io
 

docs/index.rst

@@ -1,7 +1,7 @@
 Documentation for WebbPSF
 ===============================
 
-WebbPSF is a Python package that computes simulated PSFs for the JWST instruments (and now for WFIRST too), taking into account detector pixel scales, rotations, filter profiles, and point source spectra. It is *not* a full optical model of JWST, but rather a tool for transforming optical path difference (OPD) maps, created with some other tool, into the resulting PSFs as observed with JWST's instruments.
+WebbPSF is a Python package that computes simulated point spread functions (PSFs) for NASA's JWST and WFIRST observatories. WebbPSF transforms models of telescope and instrument optical state into PSFs, taking into account detector pixel scales, rotations, filter profiles, and point source spectra. It is *not* a full optical model of JWST, but rather a tool for transforming optical path difference (OPD) maps, created with some other tool, into the resulting PSFs as observed with JWST's or WFIRST's instruments.
 
 .. figure:: ./fig_instrument_comparison.png
    :scale: 45 %
@@ -32,11 +32,11 @@ WebbPSF is a Python package that computes simulated PSFs for the JWST instrument
 
 * 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 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
+* 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, Neil Zimmerman, Robel Geda, Shannon Osborne, and Marcio Melendez Hernandez, with contributions from Jarron Leisenring, Ewan Douglas, Charles Lajoie, Megan Sosey, and the developers of  the astropy-helpers template framework.
+WebbPSF has been developed by Marshall Perrin, Joseph Long, Neil Zimmerman, Robel Geda, Shannon Osborne, Marcio Melendez Hernandez, Lauren Chambers, and Keira Brooks, with contributions from Jarron Leisenring, Ewan Douglas, Charles Lajoie, Megan Sosey, and the developers of  the astropy-helpers template framework.
 
 Getting Started with WebbPSF
 ----------------------------

docs/installation.rst

@@ -5,16 +5,21 @@ Requirements & Installation
 
 The latest released version of WebbPSF can be installed with the conda package management system or `using pip <install_pip>`_.
 
+
+Recommended best method: 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::
 
    $ source activate astroconda
 
 (Note: if you named your environment something other than ``astroconda``, change the above command appropriately.)
 
-Next, install WebbPSF (along with its dependencies and required reference data) with::
+Next, install WebbPSF (along with all its dependencies and required reference data) with::
 
    (astroconda)$ conda install webbpsf
 
+
 .. admonition:: Optional: sign up to receive announcement of updates
 
    This is entirely optional, but you may wish to sign up to the mailing list ``[email protected]``. This is a low-traffic moderated announce-only list, to which we will periodically post announcements of updates to this software.
@@ -43,47 +48,31 @@ Upgrading to the latest version is done with ``conda update -n webbpsf-env --all
 Installing with pip
 -------------------
 
-**If you have Python 2.7, 3.4, or 3.5 already installed another way**, WebbPSF and its underlying optical library POPPY may be installed from the `Python Package Index <http://pypi.python.org/pypi>`_ in the usual manner for Python packages. ::
+WebbPSF and its underlying optical library POPPY may be installed from the `Python Package Index <http://pypi.python.org/pypi>`_ in the usual manner for Python packages. ::
 
     $ pip install --upgrade webbpsf
     [... progress report ...]
 
     Successfully installed webbpsf
 
-Note that ``pip install webbpsf`` only installs the program code. You still must 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 below <data_install>`.**
 To obtain source spectra for calculations, you should also follow :ref:`installation instructions for pysynphot <pysynphot_install>`.
 
-To use the Jupyter Notebook GUI, you will need to install ``ipywidgets``::
-
-   $ pip install ipywidgets
-   $ jupyter nbextension enable --py --sys-prefix widgetsnbextension
-
-(See `the ipywidgets README <https://github.com/ipython/ipywidgets#install>`_ for more info.)
-
-.. tip::
-
-   If you wish to install WebbPSF on a machine for which you do not have administrative access, you can do so by using Python's
-   built-in `"--user" mechanism  <http://docs.python.org/2/install/#alternate-installation-the-user-scheme>`_
-   for installing packages into your home directory. ::
-
-      $ pip install webbpsf --user
-
-.. warning::
-
-   If you get the message ``SystemError: Cannot compile 'Python.h'. Perhaps you need to install python-dev|python-devel.`` during install *even when Python.h is available*, this means ``setup.py`` was unable to install NumPy. This can sometimes be fixed by executing ``pip install numpy`` separately, before installing WebbPSF. See the bug report at `numpy/numpy#2434 <https://github.com/numpy/numpy/issues/2434>`_ for details.
 
 .. _pysynphot_install:
 
 Installing or updating pysynphot
 --------------------------------
 
-Pysynphot is an optional dependency, but is highly recommended.  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 `here in the POPPY docs <http://poppy-optics.readthedocs.io/en/stable/installation.html#installing-or-updating-pysynphot>`_.
 
 .. _data_install:
 
 Installing the Required Data Files
 ----------------------------------
 
+*If you install via pip or manually*, you must install the data files yourself. If you install via Conda, the data files are automatically installed, in which case you can skip this section. 
+
 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.7.0.tar.gz <http://www.stsci.edu/~mperrin/software/webbpsf/webbpsf-data-0.7.0.tar.gz>`_  [approx. 240 MB]
@@ -111,13 +100,13 @@ You should now be able to successfully ``import webbpsf`` in a Python session, o
 Software Requirements
 ---------------------
 
-**Required Python version**: WebbPSF is supported on both Python 2.7 and 3.4+.
+**Required Python version**: WebbPSF 0.8 and above require Python 3.5 or higher.
 
 **Required Python packages**:
 
 * 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>`_, 1.0 or more recent.
-* `POPPY <https://pypi.python.org/pypi/poppy>`_, 0.5.0 or more recent.
+* `Astropy <http://astropy.org>`_
+* `POPPY <https://pypi.python.org/pypi/poppy>`_
 
 **Recommended Python packages**:
 
@@ -129,14 +118,16 @@ Software Requirements
 **Optional Python packages**:
 
 Some calculations with POPPY can benefit from the optional packages `psutil <https://pypi.python.org/pypi/psutil>`_ and `pyFFTW <https://pypi.python.org/pypi/pyFFTW>`_, but these are not needed in general. See `the POPPY installation docs <http://poppy-optics.readthedocs.io/en/stable/installation.html>`_ for more details.
-These optional packages are only worth adding for speed improvements if you are spending substantial time running calculations.
+These optional packages are only worth adding for speed improvements if you are spending substantial time running calculations. 
+
+Additional packages are needed for the optional use of GPUs to accelerate calculations. See the POPPY documentation.
 
 .. _install_dev_version:
 
 Installing a pre-release version or contributing to WebbPSF development
 -----------------------------------------------------------------------
 
-The `WebbPSF source code repository <https://github.com/mperrin/webbpsf>`_ is hosted at GitHub, as is the repository for `POPPY <https://github.com/mperrin/poppy>`_. Users may clone or fork in the usual manner. Pull requests with code enhancements welcomed.
+The `WebbPSF source code repository <https://github.com/spacetelescope/webbpsf>`_ is hosted at GitHub, as is the repository for `POPPY <https://github.com/spacetelescope/poppy>`_. Users may clone or fork in the usual manner. Pull requests with code enhancements welcomed.
 
 To install the current development version of WebbPSF, you can use ``pip`` to install directly from a ``git`` repository. To install WebbPSF and POPPY from ``git``, uninstall any existing copies of WebbPSF and POPPY, then invoke pip as follows::
 

docs/intro.rst

@@ -14,28 +14,23 @@ GUI can provide a quicker method for many simple interactive calculations.
 Why WebbPSF?
 ------------
 
-WebbPSF replaced an older PSF simulation package,  ``JWPSF``, that was in use prior to 2011.
-From a user's perspective WebbPSF provides the following enhancements over JWPSF:
-
-* Updated to the most recent JWST pupil and OPD models, Revision V.
-* Added TFI and FGS models. TFI then updated to NIRISS.
-* Updated lists of available filters.
-* Added support for coronagraphic and spectroscopic observing modes.
-* Includes the detector rotations, particularly for MIRI and NIRSpec
-* Adds ability to set output image FOV size and pixel sampling, separate from the oversampling factor used for the optical propagation.
-* New & improved graphical user interface.
-
-
-Perhaps even more importantly, the underlying codebase has been entirely replaced and revamped. The most
-significant additions from a programmer's perspective include:
-
-* Much cleaner object-oriented interface. Better abstraction of details across layers.
-* Support for optics defined by analytic functions
-* Support for coordinate rotations and rotated optics.
-* Arbitrary oversampling for coronagraphic models.
-* Matrix Fourier Transform algorithm from Soummer et al. implemented for arbitrary detector sampling.
-* Optional parallelization for improved speed and efficient use of multiple processor cores.
-* Uses ``pysynphot`` library (same as the HST & JWST exposure time calculators) for consistent treatment of filter bandpasses and source spectra.
+For any space telescope, an ability to predict the properties of
+point spread functions (PSFs) is needed before launch for a wide
+range of preparatory science studies and tool development.
+Tools for producing high
+quality model PSFs must be easily accessible to the entire astronomical
+community.
+WebbPSF provides an easy-to-use tool for PSF simulations of JWST and WFIRST, in
+the style of the highly successful "Tiny Tim" PSF simulator for Hubble.
+
+WebbPSF
+simulations are based on a mixture of observatory design parameters and
+as-built properties. The software provides a highly flexible and scriptable toolkit in
+Python for simulating a very wide range of observing modes and science scenarios, using
+efficient computational methods (including optional parallelization and use of GPUs). WebbPSF
+is a key building block in higher-level observatory simulators, including the
+JWST `Exposure Time Calculator <https://jwst.etc.stsci.edu>`_.
+
 
 .. _intro_algorithms: