From f5e62bb624f3654b1de259031c91854b88dcce21 Mon Sep 17 00:00:00 2001
From: Daniel Welch <dwelch2102@gmail.com>
Date: Tue, 3 Oct 2017 17:04:37 -0400
Subject: [PATCH] documentation for error reporter plugin system

---
 docs/configure.rst | 40 ++++++++++++++++++++++++++++++----------
 docs/errors.rst    |  9 +++++++++
 docs/index.rst     |  1 +
 3 files changed, 40 insertions(+), 10 deletions(-)
 create mode 100644 docs/errors.rst

diff --git a/docs/configure.rst b/docs/configure.rst
index 08e94ab..3091ca6 100644
--- a/docs/configure.rst
+++ b/docs/configure.rst
@@ -353,20 +353,40 @@ scheduler
 You can disable the scheduler by setting this option to ``False``. This will reduce a little overhead if you're not using schedules, but is most useful if you want to temporarily disable all schedules.
 Defaults to ``True``
 
-rollbar
-~~~~~~~
-You can redirect worker exceptions directly to your `Rollbar <https://rollbar.com/>`__ dashboard by installing the python notifier with ``pip install rollbar`` and adding this configuration dictionary to your config::
+.. _error_reporter:
 
-    # rollbar config
+error_reporter
+~~~~~~~~~~~~~~
+You can redirect worker exceptions directly to various error reportes (for example, `Rollbar <https://rollbar.com/>` or `Sentry <https://docs.sentry.io/>`) by installing Django Q with the necessary `extras <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`.
+
+To enable installed error reporters, you must provide the configuration settings required by an error reporter extension::
+
+    # error_reporter config--rollbar example
     Q_CLUSTER = {
-        'rollbar': {
-            'access_token': '32we33a92a5224jiww8982',
-            'environment': 'Django-Q'
-        }
+        'error_reporter': {
+            'rollbar': {
+                'access_token': '32we33a92a5224jiww8982',
+                'environment': 'Django-Q'
+            }
+        } 
     }
 
-Please check the Pyrollbar `configuration reference <https://github.com/rollbar/pyrollbar#configuration-reference>`__ for more options.
-Note that you will need a `Rollbar <https://rollbar.com/>`__ account and access token to use this feature.
+For more information on error reporters and developing error reporting plugins for Django Q, see :doc:`errors<errors>`.
+
+.. rollbar
+.. ~~~~~~~
+.. You can redirect worker exceptions directly to your `Rollbar <https://rollbar.com/>`__ dashboard by installing the python notifier with ``pip install rollbar`` and adding this configuration dictionary to your config::
+
+..     # rollbar config
+..     Q_CLUSTER = {
+..         'rollbar': {
+..             'access_token': '32we33a92a5224jiww8982',
+..             'environment': 'Django-Q'
+..         }
+..     }
+
+.. Please check the Pyrollbar `configuration reference <https://github.com/rollbar/pyrollbar#configuration-reference>`__ for more options.
+.. Note that you will need a `Rollbar <https://rollbar.com/>`__ account and access token to use this feature.
 
 cpu_affinity
 ~~~~~~~~~~~~
diff --git a/docs/errors.rst b/docs/errors.rst
new file mode 100644
index 0000000..94643e2
--- /dev/null
+++ b/docs/errors.rst
@@ -0,0 +1,9 @@
+Errors
+------
+.. py:currentmodule:: django_q 
+
+Django Q uses a pluggable error reporter system based upon python `extras <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`, allowing anyone to develop plugins for error reporting and monitoring integration. Currently implemented examples include `Rollbar <https://rollbar.com/>` and `Sentry <https://docs.sentry.io/>`).
+
+Error reporting plugins register a class which implements a ``report`` method, which is invoked when a Django Q cluster encounters an error, pasing information to the particular service. Error reporters must be :ref:`configured<error_reporter>` via the ``Q_CLUSTER`` dictionary in your :file:`settings.py`. These settings are passed as kwargs upon initiation of the Error Reporter. Therefore, in order to implement a new plugin, a package must expose a class which will be instantiated with the necessary information via the ``Q_CLUSTER`` settings and implements a single ``report`` method.
+
+For example implementations, see `django-q-rollbar <https://github.com/danielwelch/django-q-rollbar>` and `django-q-sentry <https://github.com/danielwelch/django-q-sentry>`
diff --git a/docs/index.rst b/docs/index.rst
index ee4c3f0..c4ce657 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -42,6 +42,7 @@ Contents:
     Cluster <cluster>
     Monitor <monitor>
     Admin <admin>
+    Errors <errors>
     Signals <signals>
     Architecture <architecture>
     Examples <examples>