Update README

[bastibe]

The README should have links to the latest source release and PyPi.

[mgeier]

Instead of "BSD licensed" you should be probably more specific ("3-clause BSD license" or whatever the exact name is).

[bastibe]

Also, we should add a note that libsndfile is LGPL.

[bastibe]

Also, provide a changelog.

[mgeier]

I think it's also worth changing from Markdown to reStructuredText, because then the README can be re-used in the Sphinx documentation and on PyPI.

I tried this and it works great, all three pages use the same README.rst: http://github.com/spatialaudio/schunk/, http://schunk.rtfd.org/, https://pypi.python.org/pypi/SchunkMotionProtocol

[bastibe]

Sigh. I vastly prefer Markdown over RST for writing. But since the Python community has converged on RST, I agree. Maybe we can automate at least part of the conversion with pandoc.

The Github RST renderer used to be somewhat mediocre, but for simple formatting in the README it should work fine.

[mgeier]

We should add an example similar to this (see #35):

import numpy as np
import pysoundfile as sf

rms = [np.sqrt(np.mean(b**2)) for b in sf.blocks('myfile.wav', blocksize=1024, overlap=512)]

It would be better if it could be even shorter and more concise, ideally the line should have a length of no more than 79 characters.
Probably we could drop the overlap in the example.

[bastibe]

We should add an example like this to the README:

format = {'format':'RAW', 'subtype':'FLOAT', 'endian':'FILE'}
sf.write(data, 'myfile.raw', **format)
data = sf.read('myfile.raw', dtype='float32', **format)

as discussed in #54

[mgeier]

We should add the exact commands how to install PySoundFile using pip, because for new users that's not at all obvious (I know that from my own experience).
Especially, we should also advertise the --user option:

pip install PySoundFile --user

We could then add how it can be installed system-wide by removing --user from the command (assuming the user has the appropriate rights), but I think the user installation should be the default, since no special access rights are needed.

In addition, we should also mention how to install pip itself, e.g. by linking to http://pip.readthedocs.org/en/latest/installing.html.

It may also be that users have pip installed but no setuptools, then they'll have to install it before:

pip install setuptools --user

The part about python setup.py install should also include the --user option and it should explain that it has to be called in the PySoundFile/ directory (or with version number?) after unpacking the tarball (give link to PyPI).

We could also give the commands for cloning the Git repository and for python setup.py develop, but this might be better shown at a different place, see #66.

[bastibe]

Did I miss anything crucial?

[mgeier]

"documentation" is an old branch. The pages on readthedocs were still available, but after a reload, they are not anymore. For now, there is only "latest", but as soon as 0.6.0 is out, it will also be available there.

This should be the correct address: http://pysoundfile.readthedocs.org/, no need to give a separate link name.

I personally prefer the short form http://pysoundfile.rtfd.org/, but that's of course a matter of taste.

In any case, we should use the same link everywhere (currently in pysoundfile.py I used the short version).

[bastibe]

I don't like the f in rtfd. I just generally dislike swearing in official communication. Also, readthedocs is what is shown in the browser URL.

[bastibe]

Can we merge this?

[mgeier]

As soon as you remove the lie about automatically closing the file ...

[bastibe]

How about this:

If a file is opened, it is kept open for as long as the SoundFile object exists. The file is closed when the object is garbage collected, but you should use the close() method or the context manager to close the file explicitly:

Is this an acceptable compromise?

[mgeier]

Yes, I guess this would be acceptable.

It is still unnecessarily complicated and potentially confusing, but at least it is the truth (as far as I can tell) and it gives the right recommendation to our users!