Add docs

bigchaindb/events.py

@@ -9,6 +9,8 @@ class EventTypes:
     """Container class that holds all the possible
     events BigchainDB manages."""
 
+    # If you add a new Event Type, make sure to add it
+    # to the docs in docs/server/source/event-plugin-api.rst
     ALL = ~0
     BLOCK_VALID = 1
     BLOCK_INVALID = 2

bigchaindb/processes.py

@@ -4,7 +4,7 @@ import multiprocessing as mp
 import bigchaindb
 from bigchaindb import config_utils
 from bigchaindb.pipelines import vote, block, election, stale
-from bigchaindb.events import Exchange
+from bigchaindb.events import Exchange, EventTypes
 from bigchaindb.web import server, websocket_server
 
 
@@ -70,7 +70,7 @@ def start():
     logger.info('WebSocket server started')
     p_websocket_server = mp.Process(name='ws',
                                     target=websocket_server.start,
-                                    args=(exchange.get_subscriber_queue(),))
+                                    args=(exchange.get_subscriber_queue(EventTypes.BLOCK_VALID),))
     p_websocket_server.start()
 
     # start message

docs/server/source/events/event-plugin-api.rst

@@ -0,0 +1,67 @@
+The Event Plugin API [experimental]
+===================================
+
+.. danger::
+    The Event Plugin API is **experimental** and might change in the future.
+
+BigchainDB implements an internal event system that allows different software
+components to receive updates on specific topics. The WebSocket API, for example,
+is a subscriber to a stream of events called ``BLOCK_VALID``. Every time a block is
+voted valid, the WebSocket API is notified, and it sends updates to all the
+clients connected.
+
+We decided to make this internal event system public, to allow developers to
+integrate BigchainDB with other applications, such as AMPQ systems.
+
+
+Available events
+----------------
+
+The event types are listed in the source file ``bigchaindb/events.py``.
+
+.. list-table:: Event Types
+   :widths: 15 10 30
+   :header-rows: 1
+
+   * - event name
+     - event id
+     - description
+   * - BLOCK_VALID
+     - 1
+     - a block has been voted valid by the network.
+   * - BLOCK_INVALID
+     - 2
+     - a block has been voted invalid by the network.
+
+
+
+Plugin Example
+----------------
+
+We developed a minimal plugin that listens to new valid blocks and prints them
+to the console:
+
+- https://github.com/bigchaindb/bigchaindb_events_plugin_example
+
+
+Architecture of an Event Plugin
+-------------------------------
+
+Creating your own plugin is really easy, and can be summarized in few steps:
+
+1. Create a new Python package that defines the entry point ``bigchaindb.events`` in its ``setup.py``.
+2. In your entry point, define two properties:
+
+   - ``events_types``: a variable to tell BigchainDB to which events your plugin is interested.
+   - ``run``: a function that will process the events coming from BigchainDB.
+3. Install the newly created Python in the current environment.
+4. Add the plugin name to your BigchainDB configuration.
+5. (Re)start BigchainDB
+
+If the installation was successful, the plugin will be run in a different
+process. Your plugin will receive events through a ``multiprocessing.Queue``
+object. Remember: it's your plugin responsibility to consume that queue.
+
+A plugin can subscribe to more than one events by combining them using the
+**binary or** operator, e.g. in case you want to subscribe to both valid and
+invalid blocks your ``events_types`` can be ``1 | 2``.

docs/server/source/events/index.rst

@@ -0,0 +1,8 @@
+The Events API
+==============
+
+.. toctree::
+    :maxdepth: 1
+
+    websocket-event-stream-api
+    event-plugin-api

docs/server/source/index.rst

@@ -13,7 +13,7 @@ BigchainDB Server Documentation
    dev-and-test/index
    server-reference/index
    http-client-server-api
-   websocket-event-stream-api
+   events/index
    drivers-clients/index
    data-models/index
    schema/transaction