Merge lp:~eday/burrow/docs into lp:burrow

[Eric Day]

More docs, added /v1.0 to HTTP paths.

=== modified file 'burrow/backend/http.py'
--- burrow/backend/http.py	2011-04-06 02:03:37 +0000
+++ burrow/backend/http.py	2011-04-18 20:11:06 +0000
@@ -28,11 +28,11 @@
         self.server = ('localhost', 8080)
 
     def delete_accounts(self, filters={}):
-        url = self._add_parameters('/', filters=filters)
+        url = self._add_parameters('', filters=filters)
         self._request('DELETE', url)
 
     def get_accounts(self, filters={}):
-        url = self._add_parameters('/', filters=filters)
+        url = self._add_parameters('', filters=filters)
         self._request('GET', url)
 
     def delete_queues(self, account, filters={}):
@@ -93,9 +93,9 @@
                 separator = '&'
         return url
 
-    def _request(self, *args, **kwargs):
+    def _request(self, method, url, *args, **kwargs):
         connection = httplib.HTTPConnection(*self.server)
-        connection.request(*args, **kwargs)
+        connection.request(method, '/v1.0' + url, *args, **kwargs)
         response = connection.getresponse()
         if response.status == 200:
             print response.read()

=== modified file 'burrow/frontend/wsgi.py'
--- burrow/frontend/wsgi.py	2011-03-30 19:51:34 +0000
+++ burrow/frontend/wsgi.py	2011-04-18 20:11:06 +0000
@@ -69,9 +69,10 @@
         self.default_hide = self.config.get('default_hide', DEFAULT_HIDE)
         mapper = routes.Mapper()
         mapper.connect('/', action='root')
-        mapper.connect('/{account}', action='account')
-        mapper.connect('/{account}/{queue}', action='queue')
-        mapper.connect('/{account}/{queue}/{message}', action='message')
+        mapper.connect('/v1.0', action='version')
+        mapper.connect('/v1.0/{account}', action='account')
+        mapper.connect('/v1.0/{account}/{queue}', action='queue')
+        mapper.connect('/v1.0/{account}/{queue}/{message}', action='message')
         self._routes = routes.middleware.RoutesMiddleware(self._route, mapper)
 
     def run(self, thread_pool):
@@ -118,13 +119,17 @@
         return method(req, **args)
 
     @webob.dec.wsgify
-    def _delete_root(self, req):
+    def _get_root(self, req):
+        return webob.exc.HTTPOk(body=json.dumps(['v1.0'], indent=2))
+
+    @webob.dec.wsgify
+    def _delete_version(self, req):
         filters = self._parse_filters(req)
         self.backend.delete_accounts(filters)
         return webob.exc.HTTPNoContent()
 
     @webob.dec.wsgify
-    def _get_root(self, req):
+    def _get_version(self, req):
         filters = self._parse_filters(req)
         accounts = [account for account in self.backend.get_accounts(filters)]
         if len(accounts) == 0:

=== modified file 'doc/source/_static/basic.css'
--- doc/source/_static/basic.css	2011-04-07 00:10:52 +0000
+++ doc/source/_static/basic.css	2011-04-18 20:11:06 +0000
@@ -251,7 +251,7 @@
 }
 
 table.docutils td, table.docutils th {
-    padding: 1px 8px 1px 0;
+    padding: 1px 8px 1px 8px;
     border-top: 0;
     border-left: 0;
     border-right: 0;

=== modified file 'doc/source/getting_started.rst'
--- doc/source/getting_started.rst	2011-04-08 02:31:30 +0000
+++ doc/source/getting_started.rst	2011-04-18 20:11:06 +0000
@@ -16,4 +16,98 @@
 Getting Started
 ***************
 
-Coming Soon!
+System Requirements
+===================
+
+Burrow development currently targets Ubuntu Server 10.04, but should
+work on most Linux platforms with the following software:
+
+* Python 2.6
+* Eventlet 0.9.8
+* WebOb 0.9.8
+* Routes
+* Setuptools
+* Nose
+* Sphinx
+
+Getting Burrow
+==============
+
+Burrow's source code is hosted on Launchpad and managed with Bazaar.
+The current trunk can be checked out with its Launchpad alias:
+
+    ``bzr branch lp:burrow``
+
+A source tarball for the latest release of Burrow is available on the
+`Launchpad project page <https://launchpad.net/burrow>`_.
+
+Prebuilt packages for Ubuntu are not yet available.
+
+Development
+===========
+
+To get started with Burrow development (and
+other OpenStack projects), see the `How To Contribute
+<http://wiki.openstack.org/HowToContribute>`_ page on the OpenStack
+wiki. You may also want to look at the `blueprints for Burrow
+<https://blueprints.launchpad.net/burrow>`_ or ask about specific
+features on the OpenStack mailing list and IRC channel.
+
+Production
+==========
+
+It is not yet recommended to use Burrow in production environments. It
+should be production ready for small deployments with the next release,
+and larger deployments the release after.
+
+Running
+=======
+
+Once you have the required software installed and Burrow downloaded
+(either by source tarball or bzr branch), you can either run it
+directly from the source directory or install it. If you choose to
+install, run:
+
+    ``python setup.py install``
+
+If you are running from the source directory, you will want to prepend
+the ``burrow`` and ``burrowd`` commands with ``bin/``. To start the
+server, run:
+
+    ``burrowd``
+
+This should start the default server modules and enter into the server
+loop. Press CTRL-C to stop.
+
+To use the command line client, run:
+
+    ``burrow``
+
+This should output fairly detailed help messages on the available
+commands and options. To inset a message (make sure ``burrowd``
+is still running), run:
+
+    ``echo "data" | burrow create_message test_queue message_1``
+
+This will insert a new message into the queue ``test_queue`` with
+message ID ``mesage_1`` and message payload ``data``. To list the queues, run:
+
+    ``burrow get_queues``
+
+As expected, the queue ``test_queue`` should be returned. Note that
+by default the ``burrow`` command line tool uses your login ID as
+the account, so all queue and message operations are in the context
+of this account ID. You can change the default account ID with the
+``-a <account>`` option.
+
+To list all messages in ``test_queue``, run:
+
+    ``burrow get_messages test_queue``
+
+To delete the message we previously created, run:
+
+    ``burrow delete_message test_queue message_1``
+
+From here you can create more messages, delete all messages in an
+account or queue, or update one or more messages with the ``update_*``
+commands.

=== modified file 'doc/source/index.rst'
--- doc/source/index.rst	2011-04-08 23:09:42 +0000
+++ doc/source/index.rst	2011-04-18 20:11:06 +0000
@@ -27,9 +27,10 @@
 documentation can be found below.
 
 This documentation is generated by the Sphinx toolkit and lives in the
-source tree. Additional documentation on Burrow and other components
-of OpenStack can be found on the `OpenStack wiki`_.
+`Burrow source`_ tree. Additional documentation on Burrow and other
+components of OpenStack can be found on the `OpenStack wiki`_.
 
+.. _`Burrow source`: https://launchpad.net/burrow
 .. _`OpenStack wiki`: http://wiki.openstack.org
 
 Basics

=== modified file 'doc/source/introduction.rst'
--- doc/source/introduction.rst	2011-04-08 02:31:30 +0000
+++ doc/source/introduction.rst	2011-04-18 20:11:06 +0000
@@ -16,4 +16,41 @@
 Introduction to Message Queues
 ******************************
 
-Coming Soon!
+Message queues can be utilized by applications for a number of reasons,
+but at the core they are used to enable asynchronous communication
+between different threads of execution. Messages may be passed between
+threads, process, machines, or data centers. At a higher level, they
+are usually used to distributed work to other threads or programs that
+are more suitable or even specialized. For example, queue consumers
+may send email, resize images, or start virtual machines on behalf
+of the caller. For a more general introduction to message queues,
+see the Wikipedia page on `Message Queues`_.
+
+.. _`Message Queues`: http://en.wikipedia.org/wiki/Message_queue
+
+Message queue solutions are usually designed with a specific scope or
+environment in mind. For example, the Python :mod:`Queue` module is
+designed to be used within the same process. `RabbitMQ`_ is primarily
+designed for clustered applications. The protocols used for network
+based queues play a role in this as well, for example previous
+versions of `AMQP`_ (pre 1.0) were not well suited for high-latency
+environments, but `AMQP`_ 1.0 allows pipelining to overcome this
+limitation. Some message queue solutions involve a broker to route
+messages between producers and consumers, where others such as
+`ZeroMQ`_ allow direct message passing. Some message queues such as
+`Gearman`_ are designed for a single tenant operation, where others
+like `RabbitMQ`_ allow for multiple accounts.
+
+.. _`RabbitMQ`: http://www.rabbitmq.com/
+.. _`AMQP`: http://www.amqp.org/
+.. _`ZeroMQ`: http://www.zeromq.org/
+.. _`Gearman`: http://gearman.org/
+
+Burrow is slightly different in that the focus is on distributed
+messaging (between data centers) so it's appropriate for both low
+and high-latency environments. It is also designed to handle large
+numbers of tenants in order to be suitable for a large public cloud
+deployments. Beyond being a simple message queue, Burrow also provides
+a fanout event notification mechanism so a single message may be read
+by multiple readers. Readers can ask for new messages with a marker
+to maintain the state of the last seen message.

=== modified file 'test/frontend/test_wsgi.py'
--- test/frontend/test_wsgi.py	2011-03-30 19:51:34 +0000
+++ test/frontend/test_wsgi.py	2011-04-18 20:11:06 +0000
@@ -34,18 +34,18 @@
         self.backend = self.backend_class(config)
         self.frontend = burrow.frontend.wsgi.Frontend(config, self.backend)
         self.frontend.default_ttl = 0
-        self._get_url('/', status=404)
+        self._get_url('', status=404)
         self._get_url('/a', status=404)
         self._get_url('/a/q', status=404)
 
     def tearDown(self):
         self._get_url('/a/q', status=404)
         self._get_url('/a', status=404)
-        self._get_url('/', status=404)
+        self._get_url('', status=404)
 
     def test_account(self):
         self._put_url('/a/q/1')
-        accounts = self._get_url('/')
+        accounts = self._get_url('')
         self.assertEquals(accounts, ['a'])
         self._delete_url('/a')
 
@@ -300,7 +300,7 @@
         return self._url('PUT', url, status=status, **kwargs)
 
     def _url(self, method, url, body='', status=200):
-        req = webob.Request.blank(url, method=method, body=body)
+        req = webob.Request.blank('/v1.0' + url, method=method, body=body)
         res = req.get_response(self.frontend)
         self.assertEquals(res.status_int, status)
         if status == 200: