--- a/pyforge/docs/guides/message_bus.rst
+++ b/pyforge/docs/guides/message_bus.rst
@@ -36,11 +36,11 @@
the DB (if required), and calling the appropriate reactors.
System Overview
------------------------------------------------
+-------------------------------------------------------------
PyForge uses carrot as the Python library to connect to AMQP
(and possibly STOMP for async browser notifications in the future).
-We will be using a single _durable, topic_ exchange 'exchange'.
+We will be using a single _durable,_topic_ exchange 'exchange'.
Carrot provides Publisher and Consumer classes. Each consumer defines a queue
and a (single) routing key pattern. Messages are distributed to only _one_
@@ -52,7 +52,8 @@
Since it would not be feasible to register a queue for each project, we
will be registering one or more queues per app. Each app defines a list of
(routing pattern, callback function) pairs for the routing patterns it is
-interested in. Queues will be named according to the app that registers them (a wiki's queues might be wiki_0, wiki_1, etc.).
+interested in. Queues will be named according to the app that registers
+them (a wiki's queues might be wiki_0, wiki_1, etc.).
The PyForge system automatically creates new consumer processes for you,
so you don't have to worry about any of that. The way it works is basically
@@ -64,24 +65,45 @@
new queue and register for the routing pattern p and the callback
function c
-The callback function itself is responsible for inspecting the message to determine which project generated the message and whether any other actions need to be taken.
+The callback function itself is responsible for inspecting the message
+to determine which project generated the message and whether any other
+actions need to be taken.
Routing Keys
-----------------------------------------------
-Routing keys refer to the _topic_ of a message, not necessarily to its _destination_. In this way, we decouple the producers and consumers of messages. A routing key will generally have the form _source.topic_. For instance, a message may be generated by the scm plugin with the routing key `scm.commit`. The message body would identify the project and particular SCM instance that _generated_ the message. The tracker plugin would then have a listener on the `scm.#` routing pattern and would be invoked on each SCM commit.
+Routing keys refer to the _topic_ of a message, not necessarily to its
+_destination_. In this way, we decouple the producers and consumers
+of messages. A routing key will generally have the form _source.topic_.
+For instance, a message may be generated by the scm plugin with the routing
+key `scm.commit`. The message body would identify the project and particular
+SCM instance that _generated_ the message. The tracker plugin would then
+have a listener on the `scm.#` routing pattern and would be invoked on
+each SCM commit.
-Note that in the case of email messages, the email address does _not_ directly map to the routing key; the particular project/plugin that is the destination of the email message is encoded into the message body itself.
+Note that in the case of email messages, the email address does _not_
+ directly map to the routing key; the particular project/plugin that
+ is the destination of the email message is encoded into the message
+ body itself.
How-to
----------------------------------------------------------------
-We will instantiate two AMQP exchanges, 'audit' and 'react'. Each plugin may register consumers on these exchanges.
+We will instantiate two AMQP exchanges, 'audit' and 'react'.
+Each plugin may register consumers on these exchanges.
Auditing
----------------------------------------------------------------
- The audit exchange is typically used to request a particular plugin instance in a particular project to perform some action (change the state of a ticket, index an object in SOLR, add a comment to a wiki page or ticket, etc.) To register a consumer on the auditor exchange, decorate a method in the application class with the @audit decorator, specifying which routing keys you are interested in (these decorators can be stacked). For instance, to audit messages destined for the hello_forge plugin, you might write:
+The audit exchange is typically used to request a particular
+plugin instance in a particular project to perform some action
+(change the state of a ticket, index an object in SOLR, add a
+comment to a wiki page or ticket, etc.) To register a consumer
+on the auditor exchange, decorate a method in the application
+class with the @audit decorator, specifying which routing
+keys you are interested in (these decorators can be stacked).
+For instance, to audit messages destined for the hello_forge
+plugin, you might write:
::
@@ -127,7 +149,11 @@
Decorating Class Methods
----------------------------------------------------------------
-In the above description, the consumer methods were always called in the context of a particular application instance. If you wish the consumer to be called as a class method (and to be called only once in the case of @react), simply use the `@audit` and `@react` decorators on class methods.
+In the above description, the consumer methods were always called in
+the context of a particular application instance. If you wish the
+consumer to be called as a class method (and to be called only once
+in the case of @react), simply use the `@audit` and `@react` decorators
+on class methods.
Configuring the Queues and Running the Reactor Workers
----------------------------------------------------------------