Add Sphinx API docs

[wedaly]

This is an attempt to add Sphinx API docs, addressing issue #262.

To generate the documentation locally:

cd docs
pip install -r requirements.txt
make html

Then open _build/html/index.html

To make the docstrings format correctly in the generated API documentation, I've used the napoleon docstring style to specify arguments and return values. This format seemed closest to the current docstring conventions (using "Params") while allowing Sphinx to properly format argument lists and return values.

I moved to the "Install", "Usage", and "Test" sections of the README into the documentation ".rst" files and added a link to ReadTheDocs in the readme. There's a possible race condition here, since someone will need to add the Sphinx documentation to ReadTheDocs before merging this (not sure if that's possible on rtd). If this is an issue, I can split the changes to README.md into a separate pull request.

Please let me know if I need to make any changes. Thank you!

-- Will

[dpkp]

Can this be pulled in dynamically from the VERSION file ?

[dpkp]

Any thoughts on how to automate doc creation when we tag a new release?

[wedaly]

Updated to pull the documentation version dynamically from the VERSION file.

For automating the doc build process, I've used webhooks in the past: http://read-the-docs.readthedocs.org/en/latest/webhooks.html ReadTheDocs uses the documentation version number, so when a new version is specified in the VERSION file, a new version of the documentation will appear on the site.

This does imply that the "latest" version on ReadTheDocs will always be the bleeding edge version of the documentation. I've seen some projects (like Django, for example) include a warning in the development version of the docs, with a link to the docs for the latest stable release.

[dpkp]

This doesn't look like valid Markdown. Can you update?

[wedaly]

Updated the README link to use valid markdown syntax.