[Documentation] Fixtures bundle architecture

docs/bundles/SyliusFixturesBundle/architecture.rst

@@ -0,0 +1,73 @@
+Architecture
+============
+
+Flexibility is one of the key concepts of **SyliusFixturesBundle**. This article aims to explain what design decisions
+were made in order to achieve it.
+
+Suites
+------
+
+Suites are collections of configured fixtures. They allow you to define different sets (for example - ``staging``,
+``development`` or ``big_shop``) that can be loaded independently. They are defined through YAML configuration:
+
+.. code-block:: yaml
+
+    sylius_fixtures:
+        suites:
+            my_suite_name: # Suite name as a key
+                listeners: ~
+                fixtures: ~
+
+Fixtures
+--------
+
+Fixtures are just plain old PHP objects, that change system state during their execution - they can either
+persist some entities in the database, upload some files, dispatch some events or do anything you think is needed.
+
+.. code-block:: yaml
+
+    sylius_fixtures:
+        suites:
+            my_suite_name:
+                fixtures:
+                    my_fixture: # Fixture name as a key
+                        priority: 0 # The higher priority is, the sooner the fixture will be executed
+                        options: ~ # Fixture options
+
+They implement ``Sylius\Bundle\FixturesBundle\Fixture\FixtureInterface`` and needs to be registered under
+``sylius_fixtures.fixture`` tag in order to be used in suite configuration.
+
+.. note::
+
+    The former interface extends ``ConfigurationInterface``, which is widely known from ``Configuration`` classes
+    placed under ``DependencyInjection`` directory in Symfony bundles.
+
+
+Listeners
+---------
+
+Listeners allows you to execute code at some point of fixtures loading.
+
+.. code-block:: yaml
+
+    sylius_fixtures:
+        suites:
+            my_suite_name:
+                listeners:
+                    my_listener: # Listener name as a key
+                        priority: 0 # The higher priority is, the sooner the fixture will be executed
+                        options: ~ # Listener options
+
+They implement at least one of four interfaces:
+
+     - ``Sylius\Bundle\FixturesBundle\Listener\BeforeSuiteListenerInterface`` - receives ``Sylius\Bundle\FixturesBundle\Listener\SuiteEvent`` as an arugment
+     - ``Sylius\Bundle\FixturesBundle\Listener\BeforeFixtureListenerInterface``  - receives ``Sylius\Bundle\FixturesBundle\Listener\FixtureEvent`` as an arugment
+     - ``Sylius\Bundle\FixturesBundle\Listener\AfterFixtureListenerInterface`` - receives ``Sylius\Bundle\FixturesBundle\Listener\FixtureEvent`` as an arugment
+     - ``Sylius\Bundle\FixturesBundle\Listener\AfterSuiteListenerInterface``  - receives ``Sylius\Bundle\FixturesBundle\Listener\SuiteEvent`` as an arugment
+
+.. note::
+
+    The former interface extends ``ConfigurationInterface``, which is widely known from ``Configuration`` classes
+    placed under ``DependencyInjection`` directory in Symfony bundles.
+
+In order to be used in suite configuration, they need to be registered under ``sylius_fixtures.listener``.

docs/bundles/SyliusFixturesBundle/index.rst

@@ -8,4 +8,5 @@ Configurable fixtures management for Symfony2 applications.
     :maxdepth: 2
 
     installation
+    architecture
     summary

docs/bundles/SyliusFixturesBundle/installation.rst

@@ -2,7 +2,7 @@ Installation
 ============
 
 We assume you're familiar with `Composer <http://packagist.org>`_, a dependency manager for PHP.
-Use the following command to add the bundle to your `composer.json` and download the package.
+Use the following command to add the bundle to your ``composer.json`` and download the package.
 
 If you have `Composer installed globally <http://getcomposer.org/doc/00-intro.md#globally>`_.
 

docs/bundles/SyliusFixturesBundle/summary.rst

@@ -7,7 +7,7 @@ Tests
 .. code-block:: bash
 
     $ composer install
-    $ bin/phpspec run -f pretty
+    $ bin/phpspec run
     $ bin/phpunit
 
 Bug tracking