Skip to content

Commit

Permalink
Merge pull request spacetelescope#145 from josePhoenix/docs-nbwidgets
Browse files Browse the repository at this point in the history 
Add widgetsnbextension install, rearrange installation docs
  • Loading branch information
Joseph Long authored Oct 28, 2016
2 parents 9e51158 + e353c2d commit 4c7277c
Show file tree
Hide file tree
Showing 6 changed files with 96 additions and 84 deletions.
6 changes: 0 additions & 6 deletions docs/_themes/theme_webbpsf/theme.conf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,3 @@
inherit = basic
stylesheet = bootstrap-webbpsf.css
pygments_style = sphinx

[options]
logotext1 = astro
logotext2 = py
logotext3 = :docs

36 changes: 17 additions & 19 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
# Note that not all possible configuration values are present in this file.
#
# All configuration values have a default. Some values are defined in
# the global Astropy configuration which is loaded here before anything else.
# the global Astropy configuration which is loaded here before anything else.
# See astropy.sphinx.conf for which values are set there.

# If extensions (or modules to document with autodoc) are in another directory,
Expand Down Expand Up @@ -42,8 +42,12 @@
from astropy_helpers.sphinx.conf import *

# Get configuration information from setup.cfg
from distutils import config
conf = config.ConfigParser()
try:
from ConfigParser import ConfigParser
except ImportError:
from configparser import ConfigParser
conf = ConfigParser()

conf.read([os.path.join(os.path.dirname(__file__), '..', 'setup.cfg')])
setup_cfg = dict(conf.items('metadata'))

Expand All @@ -56,9 +60,6 @@
# major.minor, call `check_sphinx_version("x.y.z")` here.
# check_sphinx_version("1.2.1")

# Remove buggy astropy extension
extensions.remove('astropy_helpers.sphinx.ext.astropyautosummary')

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns.append('_templates')
Expand All @@ -76,9 +77,9 @@

# This does not *have* to match the package name, but typically does
project = setup_cfg['package_name']
author = u'Association of Universities for Research in Astronomy'
author = setup_cfg['author']
copyright = '{0}, {1}'.format(
datetime.datetime.now().year, author)
datetime.datetime.now().year, setup_cfg['author'])

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
Expand All @@ -93,7 +94,7 @@
release = package.__version__


# -- Options for HTML output ---------------------------------------------------
# -- Options for HTML output --------------------------------------------------

# A NOTE ON HTML THEMES
# The global astropy configuration uses a custom theme, 'bootstrap-astropy',
Expand All @@ -102,12 +103,6 @@
# variables set in the global configuration. The variables set in the
# global configuration are listed below, commented out.

html_theme_options = {
'logotext1': 'WebbPSF', # white, semi-bold
'logotext2': ' for JWST & WFIRST', # orange, light
'logotext3': ' docs' # white, light
}

# Add any paths that contain custom themes here, relative to this directory.
# To use a different custom theme, add the directory containing the theme.
html_theme_path = ['_themes']
Expand Down Expand Up @@ -137,26 +132,26 @@
htmlhelp_basename = project + 'doc'


# -- Options for LaTeX output --------------------------------------------------
# -- Options for LaTeX output -------------------------------------------------

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [('index', project + '.tex', project + u' Documentation',
author, 'manual')]


# -- Options for manual page output --------------------------------------------
# -- Options for manual page output -------------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [('index', project.lower(), project + u' Documentation',
[author], 1)]


## -- Options for the edit_on_github extension ----------------------------------------
# -- Options for the edit_on_github extension ---------------------------------

if eval(setup_cfg.get('edit_on_github')):
extensions += ['astropy.sphinx.ext.edit_on_github']
extensions += ['astropy_helpers.sphinx.ext.edit_on_github']

versionmod = __import__(setup_cfg['package_name'] + '.version')
edit_on_github_project = setup_cfg['github_project']
Expand All @@ -167,3 +162,6 @@

edit_on_github_source_root = ""
edit_on_github_doc_root = "docs"

# -- Resolving issue number to links in changelog -----------------------------
github_issues_url = 'https://github.com/{0}/issues/'.format(setup_cfg['github_project'])
108 changes: 58 additions & 50 deletions docs/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,80 +3,74 @@
Requirements & Installation
===========================

The latest version of WebbPSF can be installed from either the `Python Package Index <https://pypi.python.org>`_ (PyPI) or the ``conda`` package management system.
The latest released version of WebbPSF can be installed with the conda package management system or `using pip <install_pip>`_.

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::

(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.

To subscribe, visit the `maillist.stsci.edu server <https://maillist.stsci.edu/scripts/wa.exe?SUBED1=Webbpsf-users&A=1>`_

Installing with AstroConda
--------------------------

For ease of installation, we recommend using `AstroConda <http://astroconda.readthedocs.io/en/latest/>`_, which includes WebbPSF as well as NumPy, SciPy, and other packages that can be tricky to compile on your own.

Installing AstroConda according to `their instructions <http://astroconda.readthedocs.io/en/latest/installation.html>`_ will also install WebbPSF, its dependencies, and the reference data it needs.
.. _install-with-conda:

Installing with conda (but no 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 as follows (for a conda environment named ``myenv``)::
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``)::

$ conda config --add channels http://ssb.stsci.edu/astroconda
$ source activate myenv
(myenv)$ conda install webbpsf
$ conda create -n webbpsf-env webbpsf
$ source activate webbpsf-env

Upgrading to the latest version is done with ``conda update webbpsf``.
Upgrading to the latest version is done with ``conda update -n webbpsf-env --all``.

.. warning::

You must install WebbPSF into a specific environment; our conda package will not work if installed into the "root" environment. Activate the environment where you want to install WebbPSF, and ``conda install webbpsf`` as above.
You *must* install WebbPSF into a specific environment (e.g. ``webbpsf-env``); our conda package will not work if installed into the default "root" environment.

.. _install_pip:

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. ::

$ pip install webbpsf --upgrade
$ pip install --upgrade webbpsf
[... progress report ...]

Successfully installed webbpsf

However, ``pip install webbpsf`` only installs the program code. You still must 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>`.

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.
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>`.
To obtain source spectra for calculations, you should also follow :ref:`installation instructions for pysynphot <pysynphot_install>`.

Software Requirements
---------------------
To use the Jupyter Notebook GUI, you will need to install ``ipywidgets``::

**Required Python version**: WebbPSF is supported on both Python 2.7 and 3.4+.
$ pip install ipywidgets
$ jupyter nbextension enable --py --sys-prefix widgetsnbextension

**Required Python packages**:
(See `the ipywidgets README <https://github.com/ipython/ipywidgets#install>`_ for more info.)

* 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.
.. tip::

**Recommended Python packages**:
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. ::

* `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
for pysynphot <pysynphot_install>`. Pysynphot is recommended for most users.
$ pip install webbpsf --user

**Optional Python packages**:
.. warning::

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://pythonhosted.org//poppy/installation.html>`_ for more details.
These optional packages are only worth adding for speed improvements if you are spending substantial time running calculations.
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:

Expand All @@ -96,32 +90,46 @@ Files containing such information as the JWST pupil shape, instrument throughput
2. Untar ``webbpsf-data-0.5.0.tar.gz`` into a directory of your choosing.
3. Set the environment variable ``WEBBPSF_PATH`` to point to that directory. e.g. ::

setenv WEBBPSF_PATH $HOME/data/webbpsf-data
export WEBBPSF_PATH=$HOME/data/webbpsf-data

for tcsh/csh, or::

WEBBPSF_PATH=$HOME/data/webbpsf-data; export WEBBPSF_PATH

for bash. (You will probably want to add this to your ``.cshrc`` or ``.bashrc``.)
for bash. (You will probably want to add this to your ``.bashrc``.)

You should now be able to successfully ``import webbpsf`` in a Python session, or start the GUI with the command ``webbpsfgui``.

.. warning::

If you have previously installed the data files for an earlier version of webbpsf, and then update to a newer version, the
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

Users at STScI may access the required data files from the Central Storage network. If you use bash, export these environment variables::
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"

If you are using tcsh::
Software Requirements
---------------------

**Required Python version**: WebbPSF is supported on both Python 2.7 and 3.4+.

**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.

setenv WEBBPSF_PATH /grp/jwst/ote/webbpsf-data
setenv PYSYN_CDBS /grp/hst/cdbs
**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
for pysynphot <pysynphot_install>`. Pysynphot is recommended for most users.

**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://pythonhosted.org//poppy/installation.html>`_ for more details.
These optional packages are only worth adding for speed improvements if you are spending substantial time running calculations.

.. _install_dev_version:

Expand Down
18 changes: 17 additions & 1 deletion docs/release.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,4 +63,20 @@ Finishing the release
#. Tag that commit as the release with ``git tag v0.X.Y`` and push the tags to origin and upstream with ``git push --tags origin`` and ``git push --tags upstream``
#. Edit ``setup.py`` to increment the version number in the ``VERSION`` variable and re-add the ``.dev`` suffix
#. Edit ``relnotes.rst`` to add a new heading for the upcoming version
#. Commit your edits with a message like "Back to development: version 0.X.Y+1"
#. Commit your edits with a message like "Back to development: version 0.X.Y+1"
#. Email an announcement to ``[email protected]``

Releasing a new version through AstroConda
==========================================

*Note: this uses the git tag created in the PyPI release.*

#. Fork (if needed) and clone https://github.com/astroconda/astroconda-contrib
#. If there is a new version of POPPY available to package, edit `poppy/meta.yaml <https://github.com/astroconda/astroconda-contrib/blob/master/poppy/meta.yaml>`_ to reflect the new ``version`` and ``git_tag``.
#. If the minimum needed version of the webbpsf-data package has changed in ``webbpsf/__init__.py``, edit `webbpsf-data/meta.yaml <https://github.com/astroconda/astroconda-contrib/blob/master/webbpsf-data/meta.yaml>`_ to reflect the new ``version`` and ``url``.
#. Edit `webbpsf/meta.yaml <https://github.com/astroconda/astroconda-contrib/blob/master/webbpsf/meta.yaml>`_ to reflect the new versions of POPPY and webbpsf-data, if necessary.
#. Edit in the ``git_tag`` name from ``git tag`` in the PyPI release instructions (``v0.X.Y``).
#. Commit your changes to a new branch and push to GitHub.
#. Create a pull request against ``astroconda/astroconda-contrib``.
#. Wait for SSB to build the conda packages.
#. (optional) Create a new conda environment to test the package installation following :ref:`these instructions <install-with-conda>`.
6 changes: 3 additions & 3 deletions setup.cfg
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ auto_use = True
package_name = webbpsf
description = 'Creates simulated point spread functions for the James Webb Space Telescope'
long_description = (this placeholder string will be replaced automatically with webbpsf's top-level docstring.)
author = Marshall Perrin
author_email = mperrin@stsci.edu
author = Association of Universities for Research in Astronomy
author_email = help@stsci.edu
license = BSD
url = http://www.stsci.edu/~mperrin/software/webbpsf
url = https://pythonhosted.org/webbpsf/
edit_on_github = False
github_project = mperrin/webbpsf
6 changes: 1 addition & 5 deletions setup.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
builtins._ASTROPY_SETUP_ = True

from astropy_helpers.setup_helpers import (
register_commands, adjust_compiler, get_debug_option, get_package_info)
register_commands, get_debug_option, get_package_info)
from astropy_helpers.git_helpers import get_git_devstr
from astropy_helpers.version_helpers import generate_version_py

Expand Down Expand Up @@ -74,10 +74,6 @@
# modify distutils' behavior.
cmdclassd = register_commands(PACKAGENAME, VERSION, RELEASE)

# Adjust the compiler in case the default on this platform is to use a
# broken one.
adjust_compiler(PACKAGENAME)

# Freeze build information in version.py
generate_version_py(PACKAGENAME, VERSION, RELEASE,
get_debug_option(PACKAGENAME))
Expand Down

0 comments on commit 4c7277c

Please sign in to comment.