Skip to content

Commit

Permalink
Packaging improvements based on astropy-affil template
Browse files Browse the repository at this point in the history
  • Loading branch information
@mperrin
mperrin committed Sep 18, 2013
1 parent 9e16339 commit b3bffba
Show file tree
Hide file tree
Showing 6 changed files with 332 additions and 267 deletions.
14 changes: 13 additions & 1 deletion MANIFEST.in
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,14 @@
include README.txt, CHANGES.txt
include README.rst

include distribute_setup.py
recursive-include packagename *.pyx *.c

recursive-include docs *
recursive-include licenses *
recursive-include cextern *
recursive-include scripts *

exclude *.pyc *.o
prune docs/_build
prune build

103 changes: 44 additions & 59 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# -*- coding: utf-8 -*-
# Licensed under a 3-clause BSD style license - see LICENSE.rst
#
# webbpsf documentation build configuration file, created by
# sphinx-quickstart on Mon Nov 29 15:57:01 2010.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
# Note that not all possible configuration values are present in this file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
Expand All @@ -16,12 +16,22 @@
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# sys.path.insert(0, os.path.abspath('..'))
# IMPORTANT: the above commented section was generated by sphinx-quickstart, but
# is *NOT* appropriate for astropy or Astropy affiliated packages. It is left
# commented out with this explanation to make it clear why this should not be
# done. If the sys.path entry above is added, when the astropy.sphinx.conf
# import occurs, it will import the *source* version of astropy instead of the
# version installed (if invoked as "make html" or directly with sphinx), or the
# version in the build directory (if "python setup.py build_sphinx" is used).
# Thus, any C-extensions that are needed to build the documentation will *not*
# be accessible, and the documentation will not build correctly.

# -- General configuration -----------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'numpydoc','sphinx.ext.inheritance_diagram', 'sphinx.ext.pngmath', 'sphinx.ext.autosummary', 'sphinx.ext.graphviz', 'cheeseshop']
extensions = ['sphinx.ext.autodoc', 'numpydoc','sphinx.ext.inheritance_diagram', 'sphinx.ext.pngmath', 'sphinx.ext.autosummary', 'sphinx.ext.graphviz', 'sphinxcontrib.cheeseshop']

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Expand All @@ -35,9 +45,14 @@
# The master toctree document.
master_doc = 'index'

# General information about the project.

# -- Project information ------------------------------------------------------

# This does not *have* to match the package name, but typically does
project = u'WebbPSF'
copyright = u'2010-2013, Marshall Perrin'
author = u'Marshall Perrin'
copyright = u'2010-2013, ' + 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 @@ -50,43 +65,13 @@
# The full version, including alpha/beta/rc tags.
release = webbpsf.__version__

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'

# List of documents that shouldn't be included in the build.
#unused_docs = []

# List of directories, relative to source directory, that shouldn't be searched
# for source files.
exclude_trees = []

# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []


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

Expand All @@ -101,6 +86,7 @@
#html_theme_options = {}

# 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 = []

# The name for this set of Sphinx documents. If None, it defaults to
Expand Down Expand Up @@ -161,44 +147,43 @@
#html_file_suffix = ''

# Output file base name for HTML help builder.
htmlhelp_basename = 'WebbPSFdoc'
htmlhelp_basename = project + 'doc'


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

# The paper size ('letter' or 'a4').
latex_paper_size = 'letter'

# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'

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

# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None

# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# -- Options for manual page output --------------------------------------------

# Additional stuff for the LaTeX preamble.
#latex_preamble = ''
# 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)]

# Documents to append as an appendix to all manuals.
#latex_appendices = []

# If false, no module index is generated.
#latex_use_modindex = True


# -- Options for autodoc ----------------------------

autodoc_member_order = 'bysource'

#autoclass_content = 'both'
## -- Options for the edit_on_github extension ----------------------------------------
#
#extensions += ['astropy.sphinx.ext.edit_on_github']
#
## Don't import the module as "version" or it will override the
## "version" configuration parameter
#from packagename import version as versionmod
#edit_on_github_project = "astropy/reponame"
#if versionmod.release:
# edit_on_github_branch = "v" + versionmod.version
#else:
# edit_on_github_branch = "master"
#
#edit_on_github_source_root = ""
#edit_on_github_doc_root = "docs"
133 changes: 68 additions & 65 deletions docs/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ These are optional but recommended:
* `pysynphot <https://trac6.assembla.com/astrolib>`_ 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>`.
* `pyFFTW3 <http://pypi.python.org/pypi/PyFFTW3/0.2.1>`_. The FFTW library will significantly speed up the FFTs used in coronagraphic simulations. Since direct imaging simulations use a discrete matrix FT instead, direct imaging simulation speed is unchanged. pyFFTW3 is highly recommended if you expect to perform many coronagraphic calculations.

**Additional requirement for the GUI:** The :ref:`graphical user interface<gui>` requires
Additional requirement for the GUI: The :ref:`graphical user interface<gui>` requires

* **Either** the `wxpython <http://www.wxpython.org>`_ interface to the ``wxwidgets`` widget library (recommended),

Expand All @@ -41,80 +41,29 @@ concentrate on the wxpython toolkit, but for now both are supported.
Alternatively, you can just skip using the GUI; the optical modeling classes
themselves have no dependency on these widgets.

.. _pysynphot_install:

Installing or updating pysynphot
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Pysynphot is an optional dependency, but is highly recommended.

To install or update ``pysynphot``, do the following. (See also http://stsdas.stsci.edu/pysynphot/ and https://trac6.assembla.com/astrolib). If you already have ``pysynphot``
installed, it will probably work fine without this update, but computations may be slower if you have a version earlier than 0.8. WebbPSF has most recently been tested using pysynphot v 0.8.3.


.. warning::
You may have trouble installing pysynphot, as the zip file of the source on pypi is broken. This has been
communicated upstream but not yet fixed. You may have more luck installing from an updated zip file
on testpypi: https://testpypi.python.org/pypi/pysynphot/0.9.5
To install this, use this command::
pip install -i https://testpypi.python.org/pypi pysynphot

.. comment
work without this update but computations will be slower than the current version, so we recommend updating it.
1. Download the most recent version of pysynphot from https://trac6.assembla.com/astrolib.
2. Untar that file into a temporary working directory.
3. run ``python setup.py install`` in that directory. You can delete the setup files there after you do this step.
If this is your initial installation of ``pysynphot`` you need to install the CDBS files. See the `pysynphot installation guide <https://trac6.assembla.com/astrolib/wiki/PysynphotInstallationGuide>`_. The necessary files are available from https://trac6.assembla.com/astrolib; follow the download links for "throughput files" and "model spectra". If you already have CDBS installed, then you're all set and can skip this step.


WebbPSF includes its own normalized copies of the new JWST instrumental
throughputs from the development CDBS at STScI. If you have JWST throughput
files available in your ``$PYSYN_CDBS`` directory (likely true only for
internal users at STScI), those will be used in preference to the WebbPSF
internal files, but this is not required.

.. comment
3. Untar ``CDBS-for-webb.tar.gz`` in a directory of your choosing. (Typically replacing into your current CDBS directory if already present)
4. Set the environment variable ``PYSYN_CDBS`` to point to that directory. e.g. ``setenv PYSYN_CDBS $HOME/data/CDBS``.

Installing WebbPSF
----------------------

Installing WebbPSF via PYPI
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Since version 0.2.8, WebbPSF and its underlying optical library ``poppy`` are both
WebbPSF and its underlying optical library ``poppy`` are both
installable from the `Python Package Index <http://pypi.python.org/pypi>`_ via
the standard toolchain using `pip
<http://www.pip-installer.org/en/latest/index.html>`_ or `easy_install <http://pypi.python.org/pypi/setuptools>`_. This is the recommended installation
<http://www.pip-installer.org/en/latest/index.html>`_. This is the easiest installation
method if you already have a working copy of python, numpy, and matplotlib on your computer.


.. pypi-release:: webbpsf
:prefix: Download
:class: note


.. pypi-release:: poppy
:prefix: Download
:class: note


1. Invoke pip in the usual manner::
Simply invoke pip in the usual manner::

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

``Successfully installed webbpsf``

2. You should now be able to do ``import webbpsf`` in a Python session.
You should now be able to do ``import webbpsf`` in a Python session to start WebbPSF.

3. Future versions may be installed with ``pip install --upgrade webbpsf`` when they become available.
However, the above installs only the program code. You still must download and install the data files, as :ref:`described below <data_install>`.

However, this installs only the program code. You still must download and install the data files, as :ref:`described below <data_install>`.
Future versions may be installed with ``pip install --upgrade webbpsf`` when they become available.

.. note::
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
Expand All @@ -127,23 +76,38 @@ However, this installs only the program code. You still must download and instal
Installing WebbPSF manually
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If for some reason you do not wish to use PYPI, you can just install the source file directly:
If for some reason you don't wish to use PYPI, you can just install from the source directly:

1. Download the following files.

.. pypi-release:: webbpsf
:prefix: Download
:class: note

1. Download the following file: `webbpsf-0.3.0.tar.gz <http://www.stsci.edu/~mperrin/software/webbpsf/webbpsf-0.3.0.tar.gz>`_
2. Untar ``webbpsf-0.3.0.tar.gz`` into a temporary working directory.
3. Run ``python setup.py install`` in that directory. This will install ``webbpsf`` into your Python path.

.. pypi-release:: poppy
:prefix: Download
:class: note


2. Untar each into a temporary working directory.
3. Run ``python setup.py install`` in each of those directories to install first ``poppy`` and then ``webbpsf``.


You should now be able to do ``import webbpsf`` in a Python session to start WebbPSF.

However, the above installs only the program code. You still must download and install the data files, as :ref:`described below <data_install>`.


.. note::
If you lack the filesystem permissions to write into the system python directory
(for instance, on a machine you don't have root on), you can do ``python setup.py install --user`` to install locally
in your home directory.
4. You should now be able to do ``import webbpsf`` in a Python session.



Installing WebbPSF development versions, and/or contributing to its development
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As of version 0.2.8, 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, fork, and pull diffs in the usual manner. Pull requests with code enhancements welcomed!
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.

.. _data_install:

Expand Down Expand Up @@ -181,6 +145,45 @@ This is a low-traffic moderated announce-only list, to which we will periodicall
To subscribe, email `majordomo@stsci.edu` with the message body text ``"subscribe webbpsf-users"``.


.. _pysynphot_install:

Installing or updating pysynphot
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Pysynphot is an optional dependency, but is highly recommended.

To install or update ``pysynphot``, do the following. (See also http://stsdas.stsci.edu/pysynphot/ and https://trac6.assembla.com/astrolib). WebbPSF has most recently been tested using pysynphot 0.9.5 but is known to work well with earlier versions as well.


.. warning::
You may have trouble installing pysynphot, as the zip file of the source on pypi is broken. This has been
communicated upstream but not yet fixed. You may have more luck installing from an updated zip file
on testpypi: https://testpypi.python.org/pypi/pysynphot/0.9.5
To install this, use this command::
pip install -i https://testpypi.python.org/pypi pysynphot

.. comment
work without this update but computations will be slower than the current version, so we recommend updating it.
1. Download the most recent version of pysynphot from https://trac6.assembla.com/astrolib.
2. Untar that file into a temporary working directory.
3. run ``python setup.py install`` in that directory. You can delete the setup files there after you do this step.
If this is your initial installation of ``pysynphot`` you need to install the CDBS files. See the `pysynphot installation guide <https://trac6.assembla.com/astrolib/wiki/PysynphotInstallationGuide>`_. The necessary files are available from https://trac6.assembla.com/astrolib; follow the download links for "throughput files" and "model spectra". If you already have CDBS installed, then you're all set and can skip this step.


WebbPSF includes its own normalized copies of the new JWST instrumental
throughputs from the development CDBS at STScI. If you have JWST throughput
files available in your ``$PYSYN_CDBS`` directory (likely true only for
internal users at STScI), those will be used in preference to the WebbPSF
internal files, but this is not required.

.. comment
3. Untar ``CDBS-for-webb.tar.gz`` in a directory of your choosing. (Typically replacing into your current CDBS directory if already present)
4. Set the environment variable ``PYSYN_CDBS`` to point to that directory. e.g. ``setenv PYSYN_CDBS $HOME/data/CDBS``.
Note for STScI Internal Users
---------------------------------
Expand Down
Loading

0 comments on commit b3bffba

Please sign in to comment.