Merge pull request #55 from robelgeda/docs

Initial Documentation

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "astropy_helpers"]
+	path = astropy_helpers
+	url = git://github.com/astropy/astropy-helpers

.rtd-environment.yml

@@ -1,16 +1,21 @@
 name: stips
 
 channels:
-    - astropy
+  - conda-forge
+  - astropy
+  - http://ssb.stsci.edu/astroconda
+  - defaults
 
 dependencies:
-    - python>=3.7
-    - astropy
-    - Cython
-    - matplotlib
-    - numpy >= 1.13
-    - sphinx-astropy
-    - astropy-helpers
+  - python>=3.7
+  - astropy
 
-   - pip:
-       - stsci_rtd_theme
+  # Docs
+  - sphinx
+  - docutils
+  - stsci_rtd_theme
+
+  - pip:
+    # Docs
+    - astropy_helpers
+    - sphinx_astropy

README.md

@@ -1,12 +1,11 @@
 # STScI-STIPS
 
+For documentation and installation instructions please visit https://stsci-stips.readthedocs.io
+
 ## Table of Contents
 
 * [Overview](#overview)
 * [Why use STIPS?](#why-use-stips)
-* [STIPS Python Requirements](#stips-python-requirements)
-* [STIPS Examples](#stips-examples)
-* [STIPS and Python 3](#stips-python-3-status)
 
 ## Overview
 
@@ -30,158 +29,9 @@ If extremely good instrumental accuracy is needed, STIPS is not the ideal choice
 various instrument design teams have produced much more detailed simulators. STIPS is intended to
 run reasonably quickly, and to make scene generation and observation as easy as possible.
 
-## STIPS Python Requirements
-
-STIPS currently runs under python 2.7 (and has been developed with versions 2.7.3 through 2.7.12).
-Eventually, STIPS will be made compatible with python 3.
-
-STIPS requires the following STScI-supported python packages be installed and running correctly 
-(along with any data files that the packages themselves require, as can be found in their
-documentation):
-
-* Pandeia (tested with versions 1.0 and 1.1.1)
-* Webbpsf (tested with versions between 0.4.0 and 0.6.0)
-
-STIPS also uses the following (more general) python packages:
-
-* astropy (version 1.3.2): STIPS uses astropy in order to
-	* read and write FITS files
-	* read and write ASCII tables (specifically in the IPAC format)
-	* generate Sersic profile models (if any are in the generated scene)
-* esutil (version 0.6.0): Used for retrieving data from sqlite databases in the form of numpy arrays
-* montage_wrapper (version 0.9.8): STIPS uses montage to generate mosaics. It is only imported if
-  STIPS is asked to generate a multi-detector image.
-* numpy (version 1.12.1): STIPS uses numpy extensively for almost everything that it does
-* photutils (version 0.3.2): STIPS uses photutils to determine the flux inside the half-light radius
-  in generated Sersic profiles
-* pysynphot (version 0.9.8.5): STIPS uses pysynphot to generate bandpasses, count rates, and
-  zero points. Note that pysynphot's data files (also known as the CDBS data tree) must also be
-  installed and available as indicated in pysynphot's documentation.
-* scipy (version 0.18.1): STIPS uses scipy to manipulate its internal images (zoom and rotate)
-
-Finally, STIPS requires a set of data files whose location is marked by setting the environment
-variable `stips_data`. Currently these files are available as part of the STSCI-STIPS-UI github
-project, but they should eventually be made available as a (versioned) direct download.
-
-## STIPS Examples
-
-**NOTE:** If you do not have environment variables pointing to the location of your Pandeia data,
-STIPS data, and Webbpsf data, you must set these environment variables using `os.environ` or other
-equivalent method prior to running any of these example scripts.
-
-* Creating a scene with a single stellar population and a single galaxy population, then observing
-  it with NIRCam Short F115W:
-
-  		from stips.scene_module import SceneModule
-  		from stips.observation_module import ObservationModule
-
- 		scm = SceneModule()
-
-  		stellar = {'n_stars': 50000, 
-  				   'age_low': 1.0e12, 'age_high': 1.0e12, 
-  				   'z_low': -2.0, 'z_high': -2.0,
-  				   'imf': 'salpeter', 'alpha': -2.35,
-  				   'binary_fraction': 0.1,
-  				   'distribution': 'invpow', 'clustered': True,
-  				   'radius': 100.0, 'radius_units': 'pc',
-  				   'distance_low': 20.0, 'distance_high': 20.0,
-  				   'offset_ra': 0.0, 'offset_dec': 0.0}
-  		stellar_cat_file = scm.CreatePopulation(stellar)
-
-  		galaxy = {'n_gals': 1000,
-  				  'z_low': 0.0, 'z_high': 1.0,
-  				  'rad_low': 0.01, 'rad_high': 2.0,
-  				  'sb_v_low': 30.0, 'sb_v_high': 25.0,
-  				  'distribution': 'uniform', 'clustered': False,
-  				  'radius': 200.0, 'radius_units': 'arcsec',
-  				  'offset_ra': 0.0, 'offset_dec': 0.0}
-  		galaxy_cat_file = scm.CreateGalaxies(galaxy)
-
-  		obs = {'instrument': 'NIRCamShort', 
-  		       'filters': ['F115W'], 
-  		       'detectors': 1,
-  			   'distortion': False,
-  			   'oversample': 5,
-  			   'pupil_mask': '',
-  			   'background': 'avg',
-  			   'observations_id': 1,
-  			   'exptime': 1000,
-  			   'offsets': [{'offset_id': 1, 'offset_centre': False, 'offset_ra': 0.0, 'offset_dec': 0.0, 'offset_pa': 0.0}]}
-  		obm = ObservationModule(obs)
-  		obm.nextObservation()
-  		output_stellar_catalogues = obm.addCatalogue(stellar_cat_file)
-  		output_galaxy_catalogues = obm.addCatalogue(galaxy_cat_file)
-  		psf_file = obm.addError()
-  		fits_file, mosaic_file, params = obm.finalize(mosaic=False)
-
-  In this case, the output FITS file will be in the variable `fits_file`, and the output catalogues
-  (showing the actual count rate and position of the sources observed) will be in the variables
-  `output_stellar_catalogues` and `output_galaxy_catalogues`.
-* Creating a scene from an existing source catalogue `input_sources.txt`, and observing it with the
-  WFIRST WFI "F129" filter, offset by 0.5 degrees in RA, and rotated by 27 degrees:
-
-  		from stips.observation_module import ObservationModule
-
-  		obs = {'instrument': 'WFI', 
-  		       'filters': ['F129'],
-  		       'detectors': 1,
-  			   'distortion': False,
-  			   'oversample': 5,
-  			   'pupil_mask': '',
-  			   'background': 'avg',
-  			   'observations_id': 1,
-  			   'exptime': 1000,
-  			   'offsets': [{'offset_id': 1, 'offset_centre': False, 'offset_ra': 0.5, 'offset_dec': 0.0, 'offset_pa': 27.0}]}
-		scene_general = {'ra': 256.274799731, 'dec': 22.6899695529, 'pa': 0.0, 'seed': 1}
-  		obm = ObservationModule(obs, scene_general=scene_general)
-  		obm.nextObservation()
-  		source_count_catalogues = obm.addCatalogue('input_sources.txt')
-  		psf_file = obm.addError()
-  		fits_file, mosaic_file, params = obm.finalize(mosaic=False)
-
-  In this case, the output catalogue(s) will show the actual applied count rates. Whether there is
-  only one output catalogue or two depends on the input catalogue format.
-
-## STIPS Python 3 Status
-
-STIPS was originally designed with and for python 2, but work has recently begun on converting it to 
-python 3. Currently, STIPS is known to be importable from python 3, and the STIPS observation
-module has been used with an internal-format catalogue. Any issues encountered when using STIPS with
-python 3 should be reported on 
-[STIPS Github Issue 16](https://github.com/spacetelescope/STScI-STIPS/issues/16).
-
-To install, in bash:
-
-Once you have a version of "conda" on your machine, Obtain a copy of cdbs and pandeia _data-1.0 (need link to these), and note their paths:
-
-export PYSYN_CDBS="[path to cdbs]"
-
-export pandeia_refdata="[path to pandeia_data-1.0]"
-
-conda create -n forSTIPS python=2.7.12 astropy=1.3.2 numpy=1.12.1 scipy=0.18.1 photutils=0.3.2 pysynphot=0.9.8.5 webbpsf=0.6
-
-source activate forSTIPS
-
-echo $WEBBPSF_PATH #if this is defined, then the environment should be correct
-
-pip install "esutil==0.6.0"
-
-pip install "montage-wrapper==0.9.9"
-
-pip install "jwst_backgrounds==1.1.1"
-
-pip install "pandeia.engine==1.0"
-
-#to install in /local/tmp/Work  Substitute directory as needed
-
-cd /local/tmp/Work
-
-git clone https://github.com/spacetelescope/STScI-STIPS-UI.git
-
-export stips_data="/local/tmp/Work/STScI-STIPS-UI/sim_input/stips_data"
+Developed by Brian York ([@york-stsci](https://github.com/york-stsci)) and
+Robel Geda ([@robelgeda](https://github.com/robelgeda)).
 
-git clone https://github.com/spacetelescope/STScI-STIPS.git
 
-cd STScI-STIPS
+![Alt text](docs/wfirst_figures/stips_demo.png?raw=true "WFIRST Image of a Star Cluster and Background Galaxies")
 
-python setup.py install

ah_bootstrap.py

@@ -79,6 +79,13 @@
 
 # Start off by parsing the setup.cfg file
 
+_err_help_msg = """
+If the problem persists consider installing astropy_helpers manually using pip
+(`pip install astropy_helpers`) or by manually downloading the source archive,
+extracting it, and installing by running `python setup.py install` from the
+root of the extracted source code.
+"""
+
 SETUP_CFG = ConfigParser()
 
 if os.path.exists('setup.cfg'):
@@ -156,6 +163,8 @@
     sys.stderr.write("ERROR: setuptools 30.3 or later is required by astropy-helpers\n")
     sys.exit(1)
 
+SETUPTOOLS_LT_42 = LooseVersion(setuptools.__version__) < LooseVersion('42')
+
 # typing as a dependency for 1.6.1+ Sphinx causes issues when imported after
 # initializing submodule with ah_boostrap.py
 # See discussion and references in
@@ -526,7 +535,9 @@ def get_option_dict(self, command_name):
                         opts['find_links'] = ('setup script', find_links)
                     if index_url is not None:
                         opts['index_url'] = ('setup script', index_url)
-                    if allow_hosts is not None:
+                    # For setuptools>=42, the allow_hosts option can't
+                    # be used because pip doesn't support it.
+                    if allow_hosts is not None and SETUPTOOLS_LT_42:
                         opts['allow_hosts'] = ('setup script', allow_hosts)
                 return opts
 
@@ -921,14 +932,6 @@ def _silence():
         sys.stderr = old_stderr
 
 
-_err_help_msg = """
-If the problem persists consider installing astropy_helpers manually using pip
-(`pip install astropy_helpers`) or by manually downloading the source archive,
-extracting it, and installing by running `python setup.py install` from the
-root of the extracted source code.
-"""
-
-
 class _AHBootstrapSystemExit(SystemExit):
     def __init__(self, *args):
         if not args:
@@ -1007,4 +1010,4 @@ def use_astropy_helpers(**kwargs):
 
     # Create a new bootstrapper with the updated configuration and run it
     BOOTSTRAPPER = _Bootstrapper(**config)
-    BOOTSTRAPPER.run()
+    BOOTSTRAPPER.run()

docs/conf.py

@@ -50,6 +50,7 @@ def setup(app):
     from ConfigParser import ConfigParser
 except ImportError:
     from configparser import ConfigParser
+
 conf = ConfigParser()
 
 conf.read([os.path.join(os.path.dirname(__file__), '..', 'setup.cfg')])
@@ -59,11 +60,8 @@ def setup(app):
 # 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('../'))
-sys.path.insert(0, os.path.abspath('../webbpsf/'))
-sys.path.insert(0, os.path.abspath('exts/'))
 
 extensions = [
-    'numfig',
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
@@ -72,6 +70,7 @@ def setup(app):
     'sphinx.ext.autosummary',
     'sphinx_automodapi.automodapi',
     ]
+
 numpydoc_show_class_members = False
 
 # -- General configuration ----------------------------------------------------
@@ -99,22 +98,18 @@ def setup(app):
 # -- Project information ------------------------------------------------------
 
 # This does not *have* to match the package name, but typically does
-project = setup_cfg['package_name']
+project = setup_cfg['name']
 author = setup_cfg['author']
-copyright = '{0}, {1}'.format(
-    datetime.datetime.now().year, setup_cfg['author'])
+copyright = '{0}, {1}'.format(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
 # built documents.
 
-__import__(setup_cfg['package_name'])
-package = sys.modules[setup_cfg['package_name']]
-
 # The short X.Y version.
-version = package.__version__.split('-', 1)[0]
+version = setup_cfg['version'].split('-', 1)[0]
 # The full version, including alpha/beta/rc tags.
-release = package.__version__
+release = setup_cfg['version']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -178,7 +173,7 @@ def setup(app):
 if eval(setup_cfg.get('edit_on_github')):
     extensions += ['astropy_helpers.sphinx.ext.edit_on_github']
 
-    versionmod = __import__(setup_cfg['package_name'] + '.version')
+    versionmod = __import__(setup_cfg['name'] + '.version')
     edit_on_github_project = setup_cfg['github_project']
     if versionmod.version.release:
         edit_on_github_branch = "v" + versionmod.version.version