From dc616db1eb48a2d014e82a4257454c829cb0a3ec Mon Sep 17 00:00:00 2001
From: Gert Van Gool <gertvangool@gmail.com>
Date: Tue, 6 Oct 2015 08:36:14 +0200
Subject: [PATCH] Adds simple signal docs

---
 README.rst                     | 27 +++++++++++++++++++++++++++
 docs/django_states/signals.rst |  5 +++++
 docs/index.rst                 |  1 +
 3 files changed, 33 insertions(+)
 create mode 100644 docs/django_states/signals.rst

diff --git a/README.rst b/README.rst
index c40d13d..6deb80b 100644
--- a/README.rst
+++ b/README.rst
@@ -137,6 +137,33 @@ exclusive (everything but these):
   class is_paid(StateGroup):
       exclude_states = ['initiated']
 
+Signals
+-------
+
+Two signals are provided (``before_state_execute`` and
+``after_state_execute``) which allow you to trigger actions surrounding state
+transitions.
+
+This might be best explained with an example:
+
+.. code:: python
+
+   from django.dispatch import receiver
+   from django_states.signals import before_state_execute, after_state_execute
+   from reversion.revisions import revision_context_manager
+
+   @receiver(before_state_execute)
+   def before_transition_handler(sender, transition, user, **kwargs):
+       revision_context_manager.start()
+
+   @receiver(after_state_execute)
+   def after_transition_handler(sender, transition, user, **kwargs):
+       revision_context_manager.set_comment('State transition: ' + transition)
+       if user is not None:
+           revision_context_manager.set_user(user)
+       revision_context_manager.end()
+
+
 State graph
 -----------
 
diff --git a/docs/django_states/signals.rst b/docs/django_states/signals.rst
new file mode 100644
index 0000000..e2eb879
--- /dev/null
+++ b/docs/django_states/signals.rst
@@ -0,0 +1,5 @@
+``django_states.signals``
+=========================
+
+.. automodule:: django_states.signals
+   :members:
diff --git a/docs/index.rst b/docs/index.rst
index 5a9c8b4..4feb5b8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -19,6 +19,7 @@ Internal API
    django_states/machine
    django_states/model_methods
    django_states/models
+   django_states/signals
    django_states/templatetags
    django_states/views