docs: Adds Custom broker class documentation

Also changes some of the variable and settings names, to make them less ambiguous.

django_q/brokers/__init__.py

@@ -159,8 +159,8 @@ def get_broker(list_key=Conf.PREFIX):
     :return:
     """
     # custom
-    if Conf.BROKER:
-        module, func = Conf.BROKER.rsplit('.', 1)
+    if Conf.BROKER_CLASS:
+        module, func = Conf.BROKER_CLASS.rsplit('.', 1)
         m = importlib.import_module(module)
         broker = getattr(m, func)
         return broker(list_key=list)

django_q/conf.py

@@ -51,8 +51,8 @@ class Conf(object):
     # ORM broker
     ORM = conf.get('orm', None)
 
-    # Custom broker
-    BROKER = conf.get('broker', None)
+    # Custom broker class
+    BROKER_CLASS = conf.get('broker_class', None)
 
     # Database Poll
     POLL = conf.get('poll', 0.2)

django_q/tests/test_brokers.py

@@ -50,12 +50,12 @@ def test_redis():
 
 
 def test_custom():
-    Conf.BROKER = 'brokers.redis_broker.Redis'
+    Conf.BROKER_CLASS = 'brokers.redis_broker.Redis'
     broker = get_broker()
     assert broker.ping() is True
     assert broker.info() is not None
     assert broker.__class__.__name__ == 'Redis'
-    Conf.BROKER = None
+    Conf.BROKER_CLASS = None
 
 
 def test_disque():

docs/brokers.rst

@@ -103,6 +103,36 @@ However for a medium message rate and scheduled tasks, this is the most convenie
 * Queue editable in Django Admin
 * See the :ref:`orm_configuration` configuration on how to set it up.
 
+
+
+Custom Broker
+-------------
+You can override the :class:`Broker` or any of its existing derived broker types.
+
+.. code-block:: python
+
+    # example Custom broker.py
+    from django_q.brokers import Broker
+
+    class CustomBroker(Broker):
+        def info(self):
+            return 'My Custom Broker'
+
+Using the :ref:`broker_class` configuration setting you can then instruct Django Q to use this instead of one of the existing brokers:
+
+.. code-block:: python
+
+    # example Custom broker class connection
+
+    Q_CLUSTER = {
+        'name': 'Custom',
+        'workers': 8,
+        'timeout': 60,
+        'broker_class: 'myapp.broker.CustomBroker'
+    }
+
+If you do write a custom broker for one of the many message queueing servers out there we don't support yet, please consider contributing it to the project.
+
 Reference
 ---------
 The :class:`Broker` class is used internally to communicate with the different types of brokers.

docs/configure.rst

@@ -292,6 +292,23 @@ mongo_db
 When using the MongoDB broker you can optionally provide a database name to use for the queues.
 Defaults to default database if available, otherwise ``django-q``
 
+.. _custom_broker:
+
+broker_class
+~~~~~~~~~~~~
+You can use a custom broker class for your cluster workers::
+
+    # example Custom broker class connection
+
+    Q_CLUSTER = {
+        'name': 'Custom',
+        'workers': 8,
+        'timeout': 60,
+        'broker_class: 'myapp.broker.CustomBroker'
+    }
+
+Make sure your ``CustomBroker`` class inherits from either the base :class:`Broker` class or one of its children.
+
 .. _bulk:
 
 bulk