Merge pull request #1561 from tiagojsag/install_docs

Installation instructions

Resources/doc/reference/installation.rst

@@ -1,49 +1,57 @@
 Installation
 ============
 
-Prerequisites
--------------
-PHP 5.3 and Symfony 2 are needed to make this bundle work ; there are also some
-Sonata dependencies that need to be installed and configured beforehand :
-
-    - `SonataCacheBundle <http://sonata-project.org/bundles/cache>`_
-    - `SonataBlockBundle <http://sonata-project.org/bundles/block>`_
-    - `SonatajQueryBundle <https://github.com/sonata-project/SonatajQueryBundle>`_
-    - `KnpMenuBundle <https://github.com/KnpLabs/KnpMenuBundle/blob/master/Resources/doc/index.md#installation>`_ (Version 1.1.*)
-    - `Exporter <https://github.com/sonata-project/exporter>`_
+SonataAdminBundle can be installed at any moment during a project's lifecycle,
+whether it's a clean Symfony2 installation or an existing project.
 
-You will need to install those in their 2.1 branches (or master if they don't
-have a similar branch). Also follow their configuration steps ; you will find
-everything you need in their installation chapter.
+1 - Downloading the code
+------------------------
 
-.. note::
-    If a dependency is already installed somewhere in your project or in
-    another dependency, you won't need to install it again.
+Use composer to manage your dependencies and download SonataAdminBundle:
 
-Translations
-~~~~~~~~~~~~
-If you wish to use default translation texts provided in this bundle, you have
-to make sure you have translator enabled in your config.
+.. code-block:: bash
 
-.. code-block:: yaml
+    php composer.phar require sonata-project/admin-bundle
 
-    # app/config/config.yml
-    framework:
-        translator: ~
+You'll be asked to type in a version constraint. 'dev-master' will get you the latest
+version, compatible with the latest Symfony2 version. Check `packagist <https://packagist.org/packages/sonata-project/admin-bundle>`_
+for older versions:
 
-Installation
-------------
+.. code-block:: bash
+
+    Please provide a version constraint for the sonata-project/jquery-bundle requirement: dev-master
 
-Download SonataAdminBundle and its dependencies to the ``vendor`` directory. You
-can use Composer for the automated process::
+2 - Selecting and downloading a storage bundle
+----------------------------------------------
 
-    php composer.phar require sonata-project/admin-bundle --no-update
-    php composer.phar require sonata-project/doctrine-orm-admin-bundle --no-update  # optional
-    php composer.phar require sonata-project/intl-bundle --no-update                # optional
-    php composer.phar require sonata-project/cache-bundle --no-update               # optional
-    php composer.phar update
+SonataAdminBundle is storage agnostic, meaning it can work with several storage 
+mechanism. Depending on which you are using on your project, you'll need to install
+one of the following bundles. In the respective links you'll find simple installation
+instructions for each of them:
 
-Next, be sure to enable these bundles in your AppKernel.php file:
+    - `SonataDoctrineORMAdminBundle <http://sonata-project.org/bundles/doctrine-orm-admin/master/doc/reference/installation.html>`_
+    - `SonataDoctrineMongoDBAdminBundle <https://github.com/sonata-project/SonataDoctrineMongoDBAdminBundle/blob/master/Resources/doc/reference/installation.rst>`_
+    - `SonataPropelAdminBundle <https://github.com/sonata-project/SonataPropelAdminBundle/blob/master/Resources/doc/reference/installation.rst>`_
+    - `SonataDoctrinePhpcrAdminBundle <https://github.com/sonata-project/SonataDoctrinePhpcrAdminBundle/blob/master/Resources/doc/reference/installation.rst>`_ 
+
+.. note::
+    Don't know which to choose? Most new users prefer SonataDoctrineORMAdmin, to interact with traditional relational databases (MySQL, PostrgreSQL, etc)
+    
+3 - Enabling SonataAdminBundle and its dependencies
+---------------------------------------------------
+
+SonataAdminBundle relies on other bundles to implement some features.
+Besides the storage layer mentioned on step 2, there are other bundles needed 
+for SonataAdminBundle to work:
+
+    - `SonataCacheBundle <http://sonata-project.org/bundles/cache/master/doc/reference/installation.html>`_
+    - `SonataBlockBundle <http://sonata-project.org/bundles/block/master/doc/reference/installation.html>`_
+    - `SonatajQueryBundle <https://github.com/sonata-project/SonatajQueryBundle/blob/documentation/Resources/doc/reference/installation.rst>`_
+    - `KnpMenuBundle <https://github.com/KnpLabs/KnpMenuBundle/blob/master/Resources/doc/index.md#installation>`_ (Version 1.1.*)
+
+These bundles are automatically downloaded by composer as a dependency of SonataAdminBundle.
+However, you have to enable them in your AppKernel.php, and configure them manually. Don't
+forget to enable SonataAdminBundle too:
 
 .. code-block:: php
 
@@ -52,14 +60,39 @@ Next, be sure to enable these bundles in your AppKernel.php file:
     {
         return array(
             // ...
+            
+            //Add you dependencies
+            new Sonata\CacheBundle\SonataCacheBundle(),
             new Sonata\BlockBundle\SonataBlockBundle(),
             new Sonata\jQueryBundle\SonatajQueryBundle(),
+            new Knp\Bundle\MenuBundle\KnpMenuBundle(),
+            //...
+            
+            //If you haven't already, add the storage bundle
+            //This example uses SonataDoctrineORMAdmin but
+            //it works the same with the alternatives
+            new Sonata\DoctrineORMAdmin\SonataDoctrineORMAdmin(),
+            
+            //Then add SonataAdminBundle
             new Sonata\AdminBundle\SonataAdminBundle(),
             // ...
         );
     }
 
-You will also need to alter your ``app/config/config.yml`` file :
+.. note::
+    If a dependency is already enabled somewhere in your AppKernel.php,
+    you don't need to enable it again.
+
+
+4 - Configuring SonataAdminBundle dependencies
+----------------------------------------------
+
+You will need to configure SonataAdminBundle's dependecies. For each of the above
+mentioned bundles, check their respective installation/configuration instructions
+files to see what changes you have to make to your Symfony2 configuration.
+
+SonataAdminBundle provides a SonataBlockBundle block that's used on the administration
+dashboard. To be able to use it, make sure it's enabled on SonataBlockBundle's configuration:
 
 .. code-block:: yaml
 
@@ -67,21 +100,43 @@ You will also need to alter your ``app/config/config.yml`` file :
     sonata_block:
         default_contexts: [cms]
         blocks:
+            # Enable the SonataAdminBundle block
             sonata.admin.block.admin_list:
                 contexts:   [admin]
+            # Your other blocks
 
-            sonata.block.service.text: ~
-            sonata.block.service.rss: ~
-
+.. note::
+    Don't worry too much if, at this point, you don't yet understand fully
+    what a block is. SonataBlockBundle is a useful tool, but it's not vital
+    that you understand right now.
+    
+5 - Cleaning up
+---------------
 
 Now, install the assets from the bundles:
 
+.. code-block:: bash
+
     php app/console assets:install web
 
-Usually when installing new bundles it's good practice to also delete your cache::
+Usually, when installing new bundles, it's good practice to also delete your cache:
+
+.. code-block:: bash
 
     php app/console cache:clear
 
+At this point, your Symfony2 installation should be fully functional, with no errors
+showing up from SonataAdminBundle or its dependencies. SonataAdminBundle is installed
+but not yet configured (more on that in the next section), so you won't be able to
+use it yet.
+
+If, at this point or during the installation, you come across any errors, don't panic:
+
+    -  Read the error message carefully. Try to find out exactly which bundle is causing the error. Is it SonataAdminBundle or one of the dependencies?
+    - Make sure you followed all the instructions correctly, for both SonataAdminBundle and it's dependencies
+    - Odds are that someone already had the same problem, and it's documented somewhere. Check `Google <http://www.google.com>`_, `Sonata Users Group <https://groups.google.com/group/sonata-users>`_, `Symfony2 Users Group <https://groups.google.com/group/symfony2>`_ and `Symfony Forum <forum.symfony-project.org>`_ to see if you can find a solution.
+    - Still no luck? Try checking the project's open issues on Github.
+
 After you have successfully installed the above bundles you need to configure
 SonataAdminBundle for administering your models. All that is needed to quickly
-set up SonataAdminBundle is described in the next chapter : :doc:`getting_started`.
+set up SonataAdminBundle is described in the :doc:`getting_started` chapter.