documentation improvements

Resources/doc/index.rst

@@ -9,7 +9,7 @@ Admin Bundle
 * `SonataDoctrinePhpcrAdminBundle <https://github.com/sonata-project/SonataDoctrinePhpcrAdminBundle>`_: integrates PHPCR with the core admin bundle (early stage)
 * `SonataPropelAdminBundle <https://github.com/sonata-project/SonataPropelAdminBundle>`_: integrates Propel with the core admin bundle (early stage)
 
-The demo website can be found in http://demo.sonata-project.org/admin/dashboard (admin as user and password).
+The demo website can be found in http://demo.sonata-project.org/admin/dashboard (``admin`` as user and password).
 
 Reference Guide
 ---------------

Resources/doc/reference/action_list.rst

@@ -90,14 +90,14 @@ Options
     * ``(m)`` stands for mandatory
     * ``(o)`` stands for optional
 
-- ``type`` (m): define the field type - mandatory for the field description itself but will try to detect the type automatically if not specified
+- ``type`` (m): defines the field type - mandatory for the field description itself but will try to detect the type automatically if not specified
 - ``template`` (o): the template used to render the field
 - ``name`` (o): the name used for the column's title
 - ``link_parameters`` (o): add link parameter to the related Admin class when the ``Admin::generateUrl`` is called
 - ``code`` (o): the method name to retrieve the related value
 - ``associated_tostring`` (o): (deprecated, use associated_property option) the method to retrieve the "string" representation of the collection element.
 - ``associated_property`` (o): property path to retrieve the "string" representation of the collection element.
-- ``identifier`` (o): if set to true a link appear on the value to edit the element
+- ``identifier`` (o): if set to true a link appears on the value to edit the element
 
 Available types and associated options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Resources/doc/reference/action_show.rst

@@ -88,9 +88,9 @@ Once you have defined this, Sonata Admin looks for it in the following location:
 
 ``src/Acme/DemoBundle/Resources/views/Admin/Display_Client.html.twig``
 
-Now that you have told Sonata Admin where to find the template, it's time to put one in there.
+Now that you have told Sonata Admin where to find the template, it is time to put one in there.
 
-The recommended way to start is to copy the default template, and paste it into it's new home.
+The recommended way to start is to copy the default template, and paste it into its new home.
 
 This ensures that you can update Sonata Admin and keep all of your hard work.
 

Resources/doc/reference/architecture.rst

@@ -38,7 +38,7 @@ automatically injected by the bundle:
 * ``ShowBuilder``: builds the show fields
 * ``ListBuilder``: builds the list fields
 * ``DatagridBuilder``: builds the filter fields
-* ``Request``: the http request received
+* ``Request``: the received http request
 * ``RouteBuilder``: allows you to add routes for new actions and remove routes for default actions
 * ``RouterGenerator``: generates the different urls
 * ``SecurityHandler``: handles permissions for model instances and actions
@@ -217,8 +217,8 @@ them are independent of the action in which they are used, like ``name`` or ``ty
 while others are used only in specific actions. More information can be found in the
 ``BaseFieldDescription`` class file.
 
-In most scenarios, you won't actually need to handle the ``FieldDescription`` yourself.
-However, it is important that you know it exists and how it's used, as it seats at the
+In most scenarios, you will not actually need to handle the ``FieldDescription`` yourself.
+However, it is important that you know it exists and how it is used, as it sits at the
 core of ``SonataAdminBundle``.
 
 Templates
@@ -267,7 +267,7 @@ Managing ``Admin`` Service
 Your ``Admin`` service definitions are parsed when Symfony2 is loaded, and handled by
 the ``Pool`` class. This class, available as the ``sonata.admin.pool`` service from the
 DIC, handles the ``Admin`` classes, lazy-loading them on demand (to reduce overhead)
-and matching each of them to a group. It's also responsible for handling the top level
+and matching each of them to a group. It is also responsible for handling the top level
 template files, administration panel title and logo.
 
 
@@ -275,8 +275,8 @@ template files, administration panel title and logo.
 Create child admins
 -------------------
 
-Let's say you have a PostAdmin and a CommentAdmin. You can optionally declare the CommentAdmin
-to be a child of the PostAdmin. This will create new routes like, for example, ``/post/{id}/comment/list``,
+Let us say you have a ``PostAdmin`` and a ``CommentAdmin``. You can optionally declare the ``CommentAdmin``
+to be a child of the ``PostAdmin``. This will create new routes like, for example, ``/post/{id}/comment/list``,
 where the comments will automatically be filtered by post.
 
 To do this, you first need to call the ``addChild`` method in your PostAdmin service configuration :

Resources/doc/reference/dashboard.rst

@@ -3,7 +3,7 @@ Dashboard
 
 The Dashboard is the main landing page. By default it lists your mapped models,
 as defined by your ``Admin`` services. This is useful to help you start using
-``SonataAdminBundle`` right away, but there's much more that you can do to take
+``SonataAdminBundle`` right away, but there is much more that you can do to take
 advantage of the Dashboard.
 
 The Dashboard is, by default, available at ``/admin/dashboard``, which is handled by

Resources/doc/reference/field_types.rst

@@ -42,14 +42,26 @@ Choice
 .. code-block:: php
 
     // For value `prog` is displayed text `In progress`. The `AcmeDemoBundle` catalogue will be used to translate `In progress` message.
-    $listMapper->add('status', 'choice', array('choices'=>array('prep'=>'Prepared', 'prog'=>'In progress', 'done'=>'Done'), 'catalogue' => 'AcmeDemoBundle'));
+    $listMapper->add(
+        'status',
+        'choice',
+        array('choices'=>array('prep'=>'Prepared', 'prog'=>'In progress', 'done'=>'Done'),
+        'catalogue' => 'AcmeDemoBundle'
+    ));
 
 ``choice`` filed type also supports multiple values that can be separated by ``delimiter`` (default delimiter is a comma ",").
 
 .. code-block:: php
 
     // For value `array('r', 'b')` is displayed `text `red | blue`.
-    $listMapper->add('colors', 'choice', array('multiple'=>true, 'delimiter'=>' | ', 'choices'=>array('r'=>'red', 'g'=>'green', 'b'=>'blue')));
+    $listMapper->add(
+        'colors',
+        'choice',
+        array(
+            'multiple' => true,
+            'delimiter' => ' | ',
+            'choices' => array('r'=>'red', 'g'=>'green', 'b'=>'blue'))
+    );
 
 Url
 ^^^

Resources/doc/reference/getting_started.rst

@@ -164,7 +164,7 @@ instance based on the class you specified before, and accepts three arguments:
 
     1. The Admin service's code (defaults to the service's name)
     2. The model which this Admin class maps (required)
-    3. The controller that will handle the administration actions (defaults to SonataAdminBundle:CRUDController)
+    3. The controller that will handle the administration actions (defaults to ``SonataAdminBundle:CRUDController()``)
 
 Usually you just need to specify the second argument, as the first and third's default
 values will work for most scenarios.
@@ -178,7 +178,7 @@ Symfony2 to load it. There are two ways to do so:
 1 - Importing it in the main config.yml
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Include your new configuration file in the main config.yml (make sure that you
+Include your new configuration file in the main ``config.yml`` (make sure that you
 use the correct file extension):
 
 .. configuration-block::
@@ -268,7 +268,7 @@ Next steps - Security
 As you probably noticed, you were able to access your dashboard and data by just
 typing in the URL. By default, the SonataAdminBundle does not come with any user
 management for ultimate flexibility. However, it is most likely that your application
-requires such feature. The Sonata Project includes a ``SonataUserBundle`` which
+requires such a feature. The Sonata Project includes a ``SonataUserBundle`` which
 integrates the very popular ``FOSUserBundle``. Please refer to the :doc:`security` section of
 this documentation for more information.
 

Resources/doc/reference/installation.rst

@@ -48,7 +48,7 @@ for SonataAdminBundle to work:
     - `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
+However, you have to enable them in your ``AppKernel.php``, and configure them manually. Don't
 forget to enable SonataAdminBundle too:
 
 .. code-block:: php
@@ -82,12 +82,15 @@ forget to enable SonataAdminBundle too:
     }
 
 .. note::
-    If a dependency is already enabled somewhere in your AppKernel.php,
+    If a dependency is already enabled somewhere in your ``AppKernel.php``,
     you don't need to enable it again.
 
 .. note::
     Since version 2.3 > SonatajQueryBundle is not required anymore as assets are available in this
-    bundle. The bundle is also registered in bower.io so you can use bower to handle your assets.
+    bundle. The bundle is also registered in `bower.io <https://github.com/sonata-project/SonataAdminBundle>`_ so
+    you can use bower to handle your assets. To make sure you get the dependencies
+    that match the version of SonataAdminBundle you are using, you can make bower
+    use the local bower dependency file, like this : ``bower require ./vendor/sonata-project/admin-bundle/bower.json``
 
 Configuring SonataAdminBundle dependencies
 ------------------------------------------
@@ -115,7 +118,7 @@ dashboard. To be able to use it, make sure it's enabled on SonataBlockBundle's c
 .. 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.
+    that you understand it right now.
 
 Cleaning up
 -----------
@@ -126,7 +129,7 @@ Now, install the assets from the bundles:
 
     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 is a good practice to also delete your cache:
 
 .. code-block:: bash
 
@@ -140,7 +143,7 @@ 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
+    - Make sure you followed all the instructions correctly, for both SonataAdminBundle and its 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.
 

Resources/doc/reference/routing.rst

@@ -251,7 +251,7 @@ can use ``hasParentFieldDescription()`` to detect this case and remove the route
     {
         protected function configureRoutes(RouteCollection $collection)
         {
-            if($this->hasParentFieldDescription()) { // prevent display of "Add new" when embedding this form
+            if ($this->hasParentFieldDescription()) { // prevent display of "Add new" when embedding this form
                 $collection->remove('create');
             }
         }

Resources/doc/reference/saving_hooks.rst

@@ -34,7 +34,7 @@ and is compatible with Doctrine ORM, Doctrine ODM and Propel. See
 `FOSUserBundle on GitHub 
 <https://github.com/FriendsOfSymfony/FOSUserBundle/>`_ for more information.
 
-The user management system requires to perform specific call when the user
+The user management system requires to perform specific calls when the user
 password or username are updated. This is how the Admin bundle can be used to
 solve the issue by using the ``preUpdate`` saving hook.
 

Resources/doc/reference/search.rst

@@ -1,7 +1,7 @@
 Search
 ======
 
-The admin comes with a basic global search available in the upper navigation menu. The search iterates over admin class
+The admin comes with a basic global search available in the upper navigation menu. The search iterates over admin classes
 and look for filter with the option ``global_search`` set to true. If you are using the ``SonataDoctrineORMBundle``
 any text filter will be set to ``true`` by default.
 

Resources/doc/reference/select2.rst

@@ -10,7 +10,7 @@ The select2 is enabled on all ``select`` form elements by default.
 Disable select2
 ---------------
 
-If you don't want to use select2 in your admin, you can disable it in config.yml.
+If you don't want to use select2 in your admin, you can disable it in ``config.yml``.
 
 .. configuration-block::
 
@@ -41,7 +41,7 @@ AllowClear
 
 Select2 parameter ``allowClear`` is handled automatically by admin. But if you want
 to overload the default functionality, you can set data attribute ``data-sonata-select2-allow-clear="true"``
-to enable ``allowClear`` or ``data-sonata-select2-allow-clear="false"`` to disable ``allowClear`` parameter.
+to enable ``allowClear`` or ``data-sonata-select2-allow-clear="false"`` to disable the ``allowClear`` parameter.
 
 .. code-block:: php