Write basic portions of documentation.

 * Strip down CONTRIBUTING from the cookiecutter boilerplate.
 * Write a minimal README.
 * Write a minimal usage.rst section.

Author: jpieper

CONTRIBUTING.rst

@@ -2,11 +2,8 @@
 Contributing
 ============
 
-Types of Contributions
-----------------------
-
 Report and Fix Bugs
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 Report or look for bugs to fix at https://github.com/jpieper/pygazebo/issues
 
@@ -55,15 +52,8 @@ Before you submit a pull request, check that it meets these guidelines:
 
 1. The pull request should include tests.
 2. If the pull request adds functionality, the docs should be updated. Put
-   your new functionality into a function with a docstring, and add the
-   feature to the list in README.rst.
-3. The pull request should work for Python 2.6, 2.7, and 3.3, and for PyPy. Check 
+   your new functionality into a function with a docstring, and update
+   the reference documentation accordingly.
+3. The pull request should work for Python 2.7. Check 
    https://travis-ci.org/jpieper/pygazebo/pull_requests
    and make sure that the tests pass for all supported Python versions.
-
-Tips
-----
-
-To run a subset of tests::
-
-	$ python -m unittest tests.test_pygazebo

README.rst

@@ -11,13 +11,40 @@ pygazebo
 .. image:: https://coveralls.io/repos/jpieper/pygazebo/badge.png
         :target: https://coveralls.io/r/jpieper/pygazebo
 
-
-Python bindings for the Gazebo multi-robot simulator.
+pygazebo provides python bindings for the Gazebo
+(http://gazebosim.org) multi-robot simulator.
 
 * Free software: Apache 2.0 License
 * Documentation: http://pygazebo.rtfd.org.
 
 Features
 --------
 
-* TODO
+* Supports publishing and subscribing to any Gazebo topics using a
+  straightforward python API.
+* Python versions of all defined Gazebo protobuf messages are
+  included.
+* Based on eventlet (http://eventlet.net), for easy concurrency support.
+
+Simple Usage
+------------
+
+The following example shows how easy it is to publish a message
+repeatedly to control a single joint in a Gazebo model.
+
+.. code-block:: python
+
+        import eventlet
+        from pygazebo import Manager
+        
+        manager = Manager(('localhost', 11345))
+        publisher = manager.advertise('/gazebo/default/model/joint_cmd',
+                                      'gazebo.msgs.JointCmd')
+
+        message = pygazebo.msg.joint_cmd_pb2.JointCmd()
+        message.axis = 0
+        message.force = 1.0
+
+        while True:
+            publisher.publish(message)
+            eventlet.sleep(1.0)

docs/usage.rst

@@ -2,6 +2,33 @@
 Usage
 ========
 
-To use pygazebo in a project::
+To use pygazebo in a project, first import, then instantiate a
+Manager::
 
-	import pygazebo
+  import pygazebo
+  
+  manager = pygazebo.Manager(('localhost', 11345))
+
+Then, individual topics can be published or subscribed using the
+`advertise` or `subscribe` methods.
+
+To publish::
+
+  publisher = manager.advertise('/gazebo/default/topic',
+                                'gazebo.msgs.GzString')
+  publisher.publish(pygazebo.msg.gz_string_pb2.GzString(data='hello'))
+
+And to subscribe::
+
+  def callback(data):
+      message = pygazebo.msg.gz_string_pb2.GzString.FromString(data)
+      print('Received message:', message.data)
+      
+  manager.subscribe('/gazebo/default/topic',
+                    'gazebo.msgs.GzString',
+                    callback)
+
+The library is built with eventlet.  Using its facilities, all
+external APIs are designed to be non-blocking.  To integrate pygazebo
+into another application, you can either use a standard eventlet hub
+integration strategy, or just poll `eventlet.sleep()` occasionally.