Merge pull request #13 from 9seconds/documentation_in_rst

Documentation in reStructuredText

MANIFEST.in

@@ -1,3 +1,3 @@
-include README.md
+include README.rst
 include LICENSE
 include *.txt

README.md → README.rst

@@ -1,67 +1,86 @@
+btsync.py
+=========
 
-     ____   ______  _____ __ __  ____     __      ____  __ __ 
+|Build Status| |Coverage Status|
+
+::
+
+     ____   ______  _____ __ __  ____     __      ____  __ __
     |    \ |      |/ ___/|  |  ||    \   /  ]    |    \|  |  |
     |  o  )|      (   \_ |  |  ||  _  | /  /     |  o  )  |  |
     |     ||_|  |_|\__  ||  ~  ||  |  |/  /      |   _/|  ~  |
     |  O  |  |  |  /  \ ||___, ||  |  /   \_  __ |  |  |___, |
     |     |  |  |  \    ||     ||  |  \     ||  ||  |  |     |
-    |_____|  |__|   \___||____/ |__|__|\____||__||__|  |____/ 
-                                                          
+    |_____|  |__|   \___||____/ |__|__|\____||__||__|  |____/
 
-[![Build Status](https://travis-ci.org/kevinjqiu/btsync.py.png?branch=master)](https://travis-ci.org/kevinjqiu/btsync.py)
-[![Coverage Status](https://coveralls.io/repos/kevinjqiu/btsync.py/badge.png?branch=master)](https://coveralls.io/r/kevinjqiu/btsync.py?branch=master)
 
 A Python API client for BitTorrent Sync
 
 
+
 Installation
-============
+------------
+
+Install from `PyPI <https://pypi.python.org>`__:
 
-Install from [PyPI](https://pypi.python.org):
+.. code-block:: bash
 
-    pip install btsync.py
+    $ pip install btsync.py
 
 Or Install from source:
 
-    git clone git@github.com:kevinjqiu/btsync.py.git
-    cd btsync.py
-    pip install -r requirements.txt
-    python setup.py install
+.. code-block:: bash
+
+    $ git clone git@github.com:kevinjqiu/btsync.py.git
+    $ cd btsync.py
+    $ pip install -r requirements.txt
+    $ python setup.py install
+
+
 
 Examples
-========
+--------
+
+You need to first download `btsync <http://labs.bittorrent.com/experiments/sync/get-started.html>`__ for your platform.
+Once it's downloaded, extract it somewhere and generate a sample config file:
 
-You need to first download [btsync](http://labs.bittorrent.com/experiments/sync/get-started.html) for your platform.  Once it's downloaded, extract it somewhere and generate a sample config file:
+.. code-block:: bash
 
-    cd /path/to/btsync
-    ./btsync --dump-sample-config > config
+    $ cd /path/to/btsync
+    $ ./btsync --dump-sample-config > config
 
 Change the default config if you wish.  The pieces of config you need for the client to connect are:
+
 - host
 - port (listening port)
 - username
 - password
 
-Run `btsync` with the config:
+Run ``btsync`` with the config:
+
+.. code-block:: bash
 
-    ./btsync --config config
+    $ ./btsync --config config
 
 With btsync running, now you can connect to it using this library:
 
 Creating a client:
 
-    In [1]: import btsync
+.. code-block:: python
 
-    In [2]: client = btsync.Client(
-    ...:     host='127.0.0.1',
-    ...:     port='1106',
-    ...:     username='admin',
-    ...:     password='password')
+    >>> import btsync
+    >>> client = btsync.Client(
+    ...     host='127.0.0.1',
+    ...     port='1106',
+    ...     username='admin',
+    ...     password='password')
 
 Listing sync folders:
 
-    In [3]: client.sync_folders
-    Out[3]:
+.. code-block:: python
+
+    >>> import pprint
+    >>> pprint.pprint(client.sync_folders)
     [{u'iswritable': 1,
     u'name': u'/home/foo/bar',
     u'peers': [{u'direct': 1,
@@ -79,72 +98,102 @@ Listing sync folders:
 
 Generate a secret for adding a sync folder:
 
-    In [7]: secret = client.generate_secret()
+.. code-block:: python
 
-    In [8]: secret
-    Out[8]:
+    >>> secret = client.generate_secret()
+    >>> pprint.pprint(secret)
     {u'rosecret': u'--------------------------------',
     u'secret': u'--------------------------------'}
 
 Add a sync folder:
 
-    In [10]: client.add_sync_folder('/tmp', secret['rosecret'])
+.. code-block:: python
 
-    In [11]: client.sync_folders[1]
-    Out[11]:
+    >>> client.add_sync_folder('/tmp', secret['rosecret'])
+    >>> pprint.pprint(client.sync_folders[1])
     {u'iswritable': 0,
     u'name': u'/tmp',
     u'peers': [],
     u'secret': u'--------------------------------',
     u'size': u'0 B in 0 files'}
 
 
+
 Development
-===========
+-----------
 
 First, you need to setup a virtualenv, as it segregates local dependencies from the system libraries nicely:
 
+.. code-block:: bash
+
     $ virtualenv btsync.py-env
 
 Activate the virtual environment:
 
+.. code-block:: bash
+
     $ cd btsync.py-env
     $ . btsync.py-env/bin/activate
 
-Clone this repo somewhere, e.g., `$HOME/src/btsync.py`:
+Clone this repo somewhere, e.g., ``$HOME/src/btsync.py``:
+
+.. code-block:: bash
 
     $ git clone git@github.com:kevinjqiu/btsync.py.git
     $ cd btsync.py
 
 Install dev dependencies:
 
+.. code-block:: bash
+
     $ pip install -r requirements-dev.txt
 
 Run tests:
 
+.. code-block:: bash
+
     $ fab test
 
 You can also generate the coverage report:
 
+.. code-block:: bash
+
     $ fab coverage
 
-To run integration tests, you need to have `btsync` executable on your `$PATH`:
+To run integration tests, you need to have ``btsync`` executable on your ``$PATH``:
+
+.. code-block:: bash
 
     $ fab test_integration
 
-Optionally, you can set an environment variable `BTSYNC` before running the test:
+Optionally, you can set an environment variable ``BTSYNC`` before running the test:
+
+.. code-block:: bash
 
     $ BTSYNC=$HOME/btsync/btsync fab test_integration
 
 To run coverage for integration tests:
 
+.. code-block:: bash
+
     $ fab coverage:integration
 
 You can also change the port the btsync instance for integration test runs on (the default port is 59999):
 
+.. code-block:: bash
+
     $ BTSYNC_PORT=55555 fab test_integration
 
+
+
 License
 =======
 
-See [LICENSE](license.txt)
+See `LICENSE <https://raw.githubusercontent.com/kevinjqiu/btsync.py/master/LICENSE>`__.
+
+
+.. |Build Status| image:: https://travis-ci.org/kevinjqiu/btsync.py.svg?branch=master
+    :target: https://travis-ci.org/kevinjqiu/btsync.py
+
+.. |Coverage Status| image:: https://coveralls.io/repos/kevinjqiu/btsync.py/badge.png?branch=master
+    :target: https://coveralls.io/r/kevinjqiu/btsync.py?branch=master

setup.py

@@ -6,7 +6,7 @@
 setup(name='btsync.py',
       version=version,
       description="A Python API client for BitTorrent Sync",
-      long_description=open('README.md').read(),
+      long_description=open('README.rst').read(),
       classifiers=[
           'Intended Audience :: Developers',
           'Environment :: Console',
@@ -21,7 +21,7 @@
       url='https://github.com/kevinjqiu/btsync.py',
       license='MIT',
       packages=find_packages(exclude=['ez_setup', 'examples', 'tests']),
-      data_files=[('.', ['requirements.txt', 'README.md', 'LICENSE'])],
+      data_files=[('.', ['requirements.txt', 'README.rst', 'LICENSE'])],
       include_package_data=True,
       zip_safe=False,
       install_requires=open('requirements.txt').readlines(),