updates readme/docs

Author: billbrod

README.md

@@ -20,10 +20,11 @@ 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.
+This is a python 3 port of Eero Simoncelli's
+[matlabPyrTools](https://github.com/LabForComputationalVision/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.
 
 **NOTE**: If you are only interested in the complex steerable pyramid, we have a
 pytorch implementation in the
@@ -49,19 +50,6 @@ 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
-
-Dependencies are documented in `setup.py`.
-
-IPython is optional. If it's not installed,
-`pyrtools.display_tools.animshow` must be called with `as_html5=False`
-(but since this is for displaying the animated image in a Jupyter /
-IPython notebook, you probably won't need that functionality).
-
-For the C code to compile, we require `gcc` version >= 6, because of
-[this
-issue](https://stackoverflow.com/questions/46504700/gcc-compiler-not-recognizing-fno-plt-option)
-
 # Pyramid resources
 
 If you would like to learn more about pyramids and why they're helpful
@@ -78,23 +66,9 @@ for image processing, here are some resources to get you started:
  - Notes from Eero Simoncelli on [the Steerable
    Pyramid](http://www.cns.nyu.edu/~eero/STEERPYR/)
 
-# Authors
-
-Rob Young and Eero Simoncelli, 7/13
-
-William Broderick, 6/17
-
-William Broderick, Pierre-Étienne Fiquet, Zhuo Wang, Zahra Kadkhodaie,
-Nikhil Parthasarathy, and the Lab for Computational Vision, 4/19
-
 # Usage:
 
-method parameters mimic the matlab function parameters except that there's no
-need to pass pyr or pind, since the pyPyrTools version pyr and pyrSize are
-properties of the class.
-
-- load modules (note that if you installed via pip, you can skip the
-  first two lines):
+- load modules:
 ```
 import pyrtools as pt
 ```
@@ -109,41 +83,29 @@ pyr = pt.pyramids.LaplacianPyramid(img)
 recon_img = pyr.recon_pyr()
 ```
 
-Please see `TUTORIALS/02_pyramids.ipynb` for more examples.  You can
-start this with: `jupyter notebook 02_pyramids.ipynb` if you have iPython
-and Jupyter installed.
+Please see `TUTORIALS/02_pyramids.ipynb` for more examples.
 
-# Testing
+# For developres
 
-All code should be considered a beta release.  By that we mean that it is being
-actively developed and tested.  You can find unit tests in
-`TESTS/unitTests.py` and run them with `python TESTS/unitTests.py`.
+## Testing
 
-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.
+You can find unit tests in `TESTS/unitTests.py` and run them with `python
+TESTS/unitTests.py`.
 
-# Build the documentation
+## Build the documentation
 
 NOTE: If you just want to read the documentation, you do not need to
 do this; documentation is built automatically on
 [readthedocs](https://pyrtools.readthedocs.io/en/latest/).
 
 However, it can be built locally as well. You would do this if you've
 made changes locally to the documentation (or the docstrings) that you
-would like to examine before pushing. 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:
+would like to examine before pushing.
 
 ```
-# install sphinx and required packages to build documentation
-conda env create -f docs/environment.yml
-# activate the environment
-conda activate pyrtools_docs
-# install pyrtools
-pip install -e .
+# create a new virtual environment and then...
+# install pyrtools with sphinx and documentation-related dependencies
+pip install -e .[docs]
 # build documentation
 cd docs/
 make html
@@ -152,10 +114,3 @@ 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.
-
-The `pyrtools_docs` environment you're creating contains the package
-`sphinx` and several extensions for it that are required to build the
-documentation. You also need to install `pyrtools` from your local
-version so that `sphinx` can import the library and grab all of the
-docstrings (you're installing the local version so you can see all the
-changes you've made).

docs/installation.rst

@@ -37,4 +37,4 @@ When installing from source on Linux or Mac, we require ``gcc`` version >= 6 in
 order for the C code to compile, because of `this issue
 <https://stackoverflow.com/questions/46504700/gcc-compiler-not-recognizing-fno-plt-option>`_
 
-When installing from source on Windows, Microsoft Visual C++ 14.0 or greater is required, which can be obtained with `Microsoft C++ Build Tools <https://visualstudio.microsoft.com/visual-cpp-build-tools/`_.
+When installing from source on Windows, Microsoft Visual C++ 14.0 or greater is required, which can be obtained with `Microsoft C++ Build Tools <https://visualstudio.microsoft.com/visual-cpp-build-tools/>`_.

docs/quickstart.rst

@@ -11,14 +11,6 @@ In the python interpreter, then call::
 
   import pyrtools as pt
 
-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::
 
   pyr = pt.pyramids.LaplacianPyramid(img)
@@ -28,7 +20,7 @@ Reconstruct image from pyramid::
   recon_img = pyr.recon_pyr()
 
 For more details, see the jupyter notebooks included in the
-`TUTORIALS/` directory, static versions of which are linked in the
+``TUTORIALS/`` directory, static versions of which are linked in the
 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/v1.0.3?filepath=TUTORIALS%2F>`_