updates readme and docs

Author: billbrod

README.md

@@ -11,16 +11,33 @@ Briefly, the tools include:
     auto-scaling options, rounding to integer zoom factors to avoid
     resampling artifacts, and useful labeling (dimensions and gray-range).
 
+This is a python 3 port of Eero Simoncelli's matlabPyrTools, but it
+does not attempt to recreate all of the matlab code from
+matlabPyrTools. The goal is to create a Python interface for the C
+code at the heart of matlabPyrTools.
+
 # Installation
 
 It's recommended you install from pip: `pip install pyrtools`. The pip
-install has been tested on Linux and on OSX. Windowsis NOT supported
+install has been tested on Linux and on OSX. Windows is NOT supported
 because of issues with the C compiler (`gcc` isn't necessarily
 installed); if you have experience with C compilation on Windows,
-please open a pull request.
-
+please open a pull request. It's possible that the way to fix this is
+to use Cython, ensuring that Cython is installed before attempting to
+run the pip command, and then adding: `from Cython.Build import
+cythonize` and wrapping the `ext_modules` in the `setup` call with
+`cythonize`, but I'm not sure.
+
+If you wish to install from the master branch, it's still recommended
+to use pip, just run `pip install .` (or `pip install -e .` if you
+want the changes you make in the directory to be reflected in your
+install) from the root directory of this project. The core of this
+code is the C code, and the pip install will compile it nicely.
 
 ## Dependencies
+
+Python 3.5, 3.6, and 3.7 all officially supported.
+
 Other requirements:
  - numpy
  - scipy
@@ -34,16 +51,24 @@ IPython is optional. If it's not installed,
 (but since this is for displaying the animated image in a Jupyter /
 IPython notebook, you probably won't need that functionality).
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/LabForComputationalVision/pyrtools/blob/master/LICENSE)
+
+[![Python version](https://img.shields.io/badge/python-3.5%7C3.6%7C3.7-blue.svg)]
+
+[![Build Status](https://travis-ci.com/LabForComputationalVision/pyrtools.svg?branch=master)](https://travis-ci.com/LabForComputationalVision/pyrtools)
+
+[![Documentation Status](https://readthedocs.org/projects/pyrtools/badge/?version=latest)](https://pyrtools.readthedocs.io/en/latest/?badge=latest)
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/LabForComputationalVision/pyrtools/master?filepath=TUTORIALS%2F)
+
 # Authors
 
 Rob Young and Eero Simoncelli, 7/13
 
 William Broderick, 6/17
 
-A python 3.6 port of Eero Simoncelli's matlabPyrTools. This port does
-not attempt to recreate all of the matlab code from matlabPyrTools.
-The goal is to create a Python interface for the C code at the heart
-of matlabPyrTools.
+William Broderick, Pierre-Étienne Fiquet, Zhuo Wang, Zahra Kadkhodaie,
+Nikhil Parthasarathy, and the Lab for Computational Vision, 4/19
 
 # Usage:
 
@@ -83,3 +108,24 @@ If you're using functions or parameters that do not have associated unit
 tests you should test this yourself to make sure the results are correct.
 You could then submit your test code, so that we can build more complete
 unit tests.
+
+# Build the documentation
+
+Documentation is built automatically on readthedocs, but can be built
+locally as well. The virtual environment required to do so is defined
+in `docs/environment.yml`, so to create that environment and build the
+docs, do the following from the project's root directory:
+
+```
+# install sphinx and required packages to build documentation
+conda env create -f docs/environment.yml
+# install pyrtools
+pip install .
+# build documentation
+cd docs/
+make html
+```
+
+The index page of the documentation will then be located at
+`docs/_build/html/index.html`, open it in your browser to navigate
+around.

docs/index.rst

@@ -1,7 +1,14 @@
-.. |license-shield| image:: https://img.shields.io/badge/license-MIT-blue.svg
+.. |license-shield| image:: https://img.shields.io/badge/license-MIT-yellow.svg
+			    :target: https://github.com/LabForComputationalVision/pyrtools/blob/master/LICENSE
 
 .. |python-version-shield| image:: https://img.shields.io/badge/python-3.5%7C3.6%7C3.7-blue.svg
 
+.. |travis| image:: https://travis-ci.com/LabForComputationalVision/pyrtools.svg?branch=master
+		    :target: https://travis-ci.com/LabForComputationalVision/pyrtools
+
+.. |binder| image:: https://mybinder.org/badge_logo.svg
+		    :target: https://mybinder.org/v2/gh/LabForComputationalVision/pyrtools/master?filepath=TUTORIALS%2F
+			     
 .. pyrtools documentation master file, created by
    sphinx-quickstart on Mon Mar 25 17:57:12 2019.
    You can adapt this file completely to your liking, but it should at least
@@ -10,7 +17,7 @@
 pyrtools
 ====================================
 
-|license-shield| |python-version-shield|
+|license-shield| |python-version-shield| |travis| |binder|
 
 Pyrtools is a python package for multi-scale image processing, adapted
 from Eero Simoncelli's `matlabPyrTools

docs/quickstart.rst

@@ -11,10 +11,13 @@ In the python interpreter, then call::
 
   import pyrtools as pt
 
-which should run without errors if the install worked correctly.
-
-Method parameters mimic the matlab function parameters except that
-there's no need to pass `pyr` or `pind`.
+which should run without errors if the install worked correctly. If
+you have an issue with the installation, it will most likely be with
+the compilation of the C code. There is hopefully a warning of this
+when you import the library, but if you get an error message along the
+lines of `lib not defined` when attempting to build a pyramid or call
+the functions `corrDn`, `upConv`, or `pointOp`, this is probably
+what's at fault.
 
 Create pyramid::
 
@@ -26,4 +29,6 @@ Reconstruct image from pyramid::
 
 For more details, see the jupyter notebooks included in the
 `TUTORIALS/` directory, static versions of which are linked in the
-navigation sidebar.
+navigation sidebar. You can play around with a live version of them in
+order to test out the code before downloading on `binder
+<https://mybinder.org/v2/gh/LabForComputationalVision/pyrtools/master?filepath=TUTORIALS%2F>`_