Add new docs for the event manager project.

docs/en/index.rst

@@ -1,10 +1,22 @@
 Event Manager Documentation
 ===========================
 
-Welcome to the Doctrine Event Manager Library documentation.
+The Doctrine Event Manager documentation is a reference guide to everything you need
+to know about the project.
 
-.. toctree::
-   :depth: 2
-   :glob:
+Getting Help
+------------
 
-   *
+If this documentation is not helping to answer questions you have about the
+Doctrine DBAL, don't panic. You can get help from different sources:
+
+-  Gitter chat room `#doctrine/event-manager <https://gitter.im/doctrine/event-manager>`_
+-  On `Stack Overflow <http://stackoverflow.com/questions/tagged/doctrine-event-manager>`_
+-  The `Doctrine Mailing List <http://groups.google.com/group/doctrine-user>`_
+-  Report a bug on `GitHub <https://github.com/doctrine/event-manager/issues>`_.
+
+Getting Started
+---------------
+
+The best way to get started is with the :doc:`Introduction <reference/index#introduction>` section
+in the documentation. Use the sidebar to browse other documentation for the Doctrine PHP DBAL.

docs/en/reference/index.rst

@@ -0,0 +1,133 @@
+Introduction
+============
+
+The Doctrine Event Manager is a simple event system used by the various Doctrine projects. It was originally built
+for the DBAL and ORM but over time other projects adopted it and now it is available as a standalone library.
+
+Installation
+============
+
+The library can easily be installed with composer.
+
+.. code-block:: sh
+
+    $ composer require doctrine/event-manager
+
+Setup
+=====
+
+The event system is controlled by the ``Doctrine\Common\EventManager`` class.
+
+.. code-block:: php
+
+    use Doctrine\Common\EventManager;
+
+    $eventManager = new EventManager();
+
+Listeners
+=========
+
+Now you are ready to listen for events. Here is an exmaple of a custom event listener named ``TestEvent``.
+
+.. code-block:: php
+
+    use Doctrine\Common\EventArgs;
+    use Doctrine\Common\EventManager;
+
+    final class TestEvent
+    {
+        public const preFoo = 'preFoo';
+        public const postFoo = 'postFoo';
+
+        /** @var EventManager */
+        private $eventManager;
+
+        /** @var bool */
+        public $preFooInvoked = false;
+
+        /** @var bool */
+        public $postFooInvoked = false;
+
+        public function __construct(EventManager $eventManager)
+        {
+            $eventManager->addEventListener(array(self::preFoo, self::postFoo), $this);
+        }
+
+        public function preFoo(EventArgs $eventArgs) : void
+        {
+            $this->preFooInvoked = true;
+        }
+
+        public function postFoo(EventArgs $eventArgs) : void
+        {
+            $this->postFooInvoked = true;
+        }
+    }
+
+    // Create a new instance
+    $testEvent = new TestEvent($eventManager);
+
+Dispatching Events
+==================
+
+Now you can dispatch events with the ``dispatchEvent()`` method.
+
+.. code-block:: php
+
+    $eventManager->dispatchEvent(TestEvent::preFoo);
+    $eventManager->dispatchEvent(TestEvent::postFoo);
+
+Removing Event Listeners
+========================
+
+You can easily remove a listener with the ``removeEventListener()`` method.
+
+.. code-block:: php
+
+    $eventManager->removeEventListener(array(TestEvent::preFoo, TestEvent::postFoo), $testEvent);
+
+Event Subscribers
+=================
+
+The Doctrine event system also has a simple concept of event subscribers. We can define a simple ``TestEventSubscriber`` class which implements the ``Doctrine\Common\EventSubscriber`` interface and implements a ``getSubscribedEvents()`` method which returns an array of events it should be subscribed to.
+
+.. code-block:: php
+
+    use Doctrine\Common\EventSubscriber;
+
+    final class TestEventSubscriber implements EventSubscriber
+    {
+        /** @var bool */
+        public $preFooInvoked = false;
+
+        public function preFoo() : void
+        {
+            $this->preFooInvoked = true;
+        }
+
+        public function getSubscribedEvents() : array
+        {
+            return array(TestEvent::preFoo);
+        }
+    }
+
+    $eventSubscriber = new TestEventSubscriber();
+    $eventManager->addEventSubscriber($eventSubscriber);
+
+.. note::
+
+    The array returned by the ``getSubscribedEvents()`` method is a simple array with the values being the event names. The subscriber must have a method that is named exactly like the event.
+
+Now when you dispatch an event, any event subscribers will be notified of that event.
+
+.. code-block:: php
+
+    $eventManager->dispatchEvent(TestEvent::preFoo);
+
+Now you can check the ``preFooInvoked`` property to see if the event subscriber was notified of the event:
+
+.. code-block:: php
+
+    if ($eventSubscriber->preFooInvoked) {
+        // the preFoo method was invoked
+    }

docs/en/sidebar.rst

@@ -0,0 +1,4 @@
+.. toctree::
+    :depth: 3
+
+    reference/index