Merge pull request #42 from bmcfee/joss-documentation-updates

Joss documentation updates

.travis.yml

@@ -26,7 +26,7 @@ before_install:
 - export PATH="$MINICONDA/bin:$PATH"
 - hash -r
 # Install conda only if necessary
-- command -v conda >/dev/null || { wget http://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh;
+- command -v conda >/dev/null || { wget http://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh;
    bash miniconda.sh -b -f -p $MINICONDA; }
 - conda config --set always_yes yes
 - conda update conda

CONTRIBUTING.md

@@ -0,0 +1,74 @@
+
+Contributing code
+=================
+
+How to contribute
+-----------------
+
+The preferred way to contribute to resampy is to fork the 
+[main repository](http://github.com/bmcfee/resampy/) on
+GitHub:
+
+1. Fork the [project repository](http://github.com/bmcfee/resampy):
+   click on the 'Fork' button near the top of the page. This creates
+   a copy of the code under your account on the GitHub server.
+
+2. Clone this copy to your local disk:
+
+          $ git clone git@github.com:YourLogin/resampy.git
+          $ cd resampy 
+
+3. Create a branch to hold your changes:
+
+          $ git checkout -b my-feature
+
+   and start making changes. Never work in the ``master`` branch!
+
+4. Work on this copy on your computer using Git to do the version
+   control. When you're done editing, do:
+
+          $ git add modified_files
+          $ git commit
+
+   to record your changes in Git, then push them to GitHub with:
+
+          $ git push -u origin my-feature
+
+Finally, go to the web page of the your fork of the resampy repo,
+and click 'Pull request' to send your changes to the maintainers for
+review. This will send an email to the committers.
+
+(If any of the above seems like magic to you, then look up the 
+[Git documentation](http://git-scm.com/documentation) on the web.)
+
+It is recommended to check that your contribution complies with the
+following rules before submitting a pull request:
+
+-  All public methods should have informative docstrings with sample
+   usage presented.
+
+You can also check for common programming errors with the following
+tools:
+
+-  Code with good unittest coverage (at least 99%), check with:
+
+          $ pip install pytest pytest-cov pytest-faulthandler
+          $ python setup.py build_ext -i
+          $ py.test --cov-report term-missing --cov resampy
+
+Documentation
+-------------
+
+You can edit the documentation using any text editor and then generate
+the HTML output by typing ``make html`` from the docs/ directory.
+The resulting HTML files will be placed in _build/html/ and are viewable 
+in a web browser. See the README file in the doc/ directory for more information.
+
+For building the documentation, you will need
+[sphinx](http://sphinx.pocoo.org/),
+[matplotlib](http://matplotlib.sourceforge.net/), and [scikit-learn](http://scikit-learn.org/).
+
+
+Note
+----
+This document was gleefully borrowed from [scikit-learn](http://scikit-learn.org/).

README.md

@@ -31,6 +31,5 @@ pip install resampy
 
 Pre-built packages can be installed with `conda` by saying:
 ```
-conda config --add channels conda-forge
-conda install resampy
+conda install -c conda-forge resampy
 ```

docs/example.rst

@@ -99,3 +99,29 @@ resampy allows you to control the design of the filters used in resampling opera
     # Or use the pre-built fast filter
     y = resampy.resample(x, sr_orig, sr_new, filter='kaiser_fast')
 
+
+Benchmarking
+============
+Benchmarking `resampy` is relatively simple, using `ipython`'s ``%timeit`` magic.
+The following example demonstrates resampling a monophonic signal of 400000 samples from
+22.05 KHz to 16 KHz using both `resampy` and `scipy.signal.resample`.
+
+.. code-block:: python
+
+    In [1]: import numpy as np
+
+    In [2]: import scipy
+    
+    In [3]: import resampy
+    
+    In [4]: x = np.random.randn(400000)
+    
+    In [5]: sr_in, sr_out = 22050, 16000
+    
+    In [6]: %timeit resampy.resample(x, sr_in, sr_out, axis=-1)
+    1 loop, best of 3: 199 ms per loop
+    
+    In [7]: %timeit scipy.signal.resample(x,
+       ...:                               int(x.shape[-1] * sr_out / float(sr_in)),
+       ...:                               axis=-1)
+    1 loop, best of 3: 6min 5s per loop

docs/index.rst

@@ -25,6 +25,45 @@ Its dependencies are `numpy <http://www.numpy.org/>`_, `scipy
 
 For a quick introduction to using `resampy`, please refer to the `Examples`_ section.
 
+Installation
+------------
+`resampy` can be installed from source through `pip`:
+
+.. code-block:: bash
+
+    pip install resampy
+
+
+Conda users can install pre-compiled packages:
+
+.. code-block:: bash
+
+    conda install -c conda-forge resampy
+
+
+Advanced users and developers may wish to install from source by cloning the source repository:
+
+.. code-block:: bash
+
+    git clone https://github.com/bmcfee/resampy.git
+    cd resampy
+    python setup.py build_ext -i
+    pip install -e .
+
+
+Running tests
+=============
+
+Developers that wish to run the included unit test suite can do so by installing from source, and then
+executing the following commands from the source directory:
+
+.. code-block:: bash
+
+    pip install -e .[tests]
+    pip install pytest pytest-cov pytest-faulthandler
+    py.test --cov-report term-missing --cov resampy
+
+
 Examples
 --------
 .. toctree::