improved the wording of the documentation

I went through and cleaned up the wording of a lot of the documentation. I
tried not to change any of the actual content too much, unless it made it a
lot easier to understand.

Resources/doc/index.rst

@@ -6,7 +6,7 @@
 Welcome to Sonata - AdminBundle's documentation!
 ================================================
 
-The ``AdminBundle`` provides a CRUD interface for model entity.
+The ``AdminBundle`` provides a CRUD interface for model entities.
 
 Reference Guide
 ---------------
@@ -36,5 +36,3 @@ Tutorial
    tutorial/creating_your_first_admin_class/defining_routing
    tutorial/creating_your_first_admin_class/defining_crud_controller
    tutorial/creating_your_first_admin_class/defining_admin_class
-   
-

Resources/doc/reference/architecture.rst

@@ -1,42 +1,43 @@
 Architecture
 ============
 
-The architecture of the bundle is mostly based on the Django Admin Project,
-which is a truly great project. More information can be found at the
+The architecture of the bundle is primarily inspired by the Django Admin
+Project, which is truly a great project. More information can be found at the
 `Django Project Website`_.
 
 The Admin Class
 ---------------
 
-The ``Admin`` class is the CRUD definition of one model. It contains
-all the configuration necessary to display a rich CRUD for the entity. From
-within an admin class, the following information can be defined:
+The ``Admin`` class represents the CRUD definition for a specific model. It
+contains all the configuration necessary to display a rich CRUD interface for
+the entity.
+
+Within the admin class, the following information can be defined:
 
 * ``list``: The fields displayed in the list table;
-* ``filter``: The fields available for filter the list;
+* ``filter``: The fields available for filtering the list;
 * ``form``: The fields used to edit the entity;
 * ``formGroups``: The group definition where a field must be displayed (edit form)
-* The batch actions: Actions that can be performed on a group of entities
+* Batch actions: Actions that can be performed on a group of entities
   (e.g. bulk delete)
 
 If a field is associated with another entity (and that entity also has an
 ``Admin`` class), then the related ``Admin`` class will be accessible from
-within the first ``Admin`` class.
+within the first class.
 
-The admin class is a service implementing the ``AdminInterface``, meaning that
-only required dependencies are injected:
+The admin class is a service implementing the ``AdminInterface`` interface,
+meaning that the following required dependencies are automatically injected:
 
-* ``ListBuilder`` : build the list fields
-* ``FormContractor`` : construct the form using the Symfony ``FormBuilder``
-* ``DatagridBuilder`` : build the filter fields
-* ``Router`` : generate the different urls
+* ``ListBuilder``: builds the list fields
+* ``FormContractor``: constructs the form using the Symfony ``FormBuilder``
+* ``DatagridBuilder``: builds the filter fields
+* ``Router``: generates the different urls
 * ``Request`` 
-* ``ModelManager`` : Service which handle specific ORM code
+* ``ModelManager``: Service which handles specific ORM code
 * ``Translator``
 
-
-Therefore, you have access to every service you want by injecting them into the
-admin class, like:
+Therefore, you can gain access to any service you want by injecting them into
+the admin class, like so:
 
 .. code-block:: xml
 
@@ -54,7 +55,6 @@ admin class, like:
 
 Here, the FOS' User Manager is injected into the Post service.
 
-
 Field Definition
 ----------------
 
@@ -80,35 +80,35 @@ template extends two layouts:
 * ``AdminBundle::ajax_layout.twig``
 
 The base templates can be configured in the Service Container. So you can easily tweak
-the layout upon your requirements.
+the layout to suit your requirements.
 
 Each field is rendered in three different ways and each has its own Twig
 template. For example, for a field with a ``text`` type, the following three
 templates will be used:
 
-* ``edit_text.twig``: template used in the form edition
+* ``edit_text.twig``: template used in the edit form
 * ``filter_text.twig``: template used in the filter box
 * ``list_text.twig``: template used in the list table
 
 CrudController
 --------------
 
-The controller contains the basic CRUD actions, the controller is
-related to one ``Admin`` class by mapping the controller name to the correct
-``Admin`` instance.
+The controller contains the basic CRUD actions, it controller is related to one
+``Admin`` class by mapping the controller name to the correct ``Admin``
+instance.
 
-All actions can be easily overwritten depending on the project's requirements.
+Any or all actions can be overwritten to suit the project's requirements.
 
 The controller uses the ``Admin`` class to construct the different actions.
-Inside the controller, the ``Admin`` object is accessible through the ``configuration``
-property.
+Inside the controller, the ``Admin`` object is accessible through the
+``configuration`` property.
 
 Obtaining an ``Admin`` Service
 ------------------------------
 
-``Admin`` definition are accessible through the 'sonata.admin.pool' service or directly from the DIC.
-The ``Admin`` definitions are lazy loaded from the DIC to avoid overhead.
-
+``Admin`` definitions are accessible through the 'sonata.admin.pool' service or
+directly from the DIC. The ``Admin`` definitions are lazy loaded from the DIC to
+reduce overhead.
 
 Declaring a new Admin class
 ---------------------------
@@ -127,7 +127,7 @@ Once you have created an admin class, you must declare the class to use it. Like
         <argument>SonataNewsBundle:PostAdmin</argument>
     </service>
 
-Or if you're using an YML configuration file,
+Or if you're using a YML configuration file,
 
 .. code-block:: yml
 
@@ -139,4 +139,4 @@ Or if you're using an YML configuration file,
           arguments: [null, Sonata\NewsBundle\Entity\Post, SonataNewsBundle:PostAdmin]
 
 
-.. _`Django Project Website`: http://www.djangoproject.com/
+.. _`Django Project Website`: http://www.djangoproject.com/

Resources/doc/reference/dashboard.rst

@@ -4,7 +4,6 @@ Dashboard
 The dashboard is the main landing page. For now the dashboard lists the
 different admin areas available.
 
-
 .. image:: ../images/dashboard.png 
            :alt: Dashboard
-           :width: 50%
+           :width: 50%

Resources/doc/reference/filter_field_definition.rst

@@ -44,22 +44,24 @@ Types available
 - string
 - text
 
-if no type is set, the Admin class will use the one set in the doctrine mapping definition.
+If no type is set, the Admin class will use the one set in the Doctrine mapping
+definition.
 
 Tweak it!
 ---------
 
-- It is possible to tweak the default template by setting a ``template`` key in the 
-  options array.
-- If the project required specific behaviors, they can be implemented in the
+- It is possible to change the default template by setting a ``template`` key
+  in the options array.
+- If the project requires specific behaviors, they can be implemented in the
   ``configureFilterFields()`` method.
-  
+
 Advanced usage
 --------------
 
-If you want to create a custom callback filter, this is how to do. ``getWithOpenCommentField`` and
-``getWithOpenCommentFilter``  are callback method used to define the field type and how to filter 
-the provided value.
+To create a custom callback filter, two methods need to be implemented; one to
+define the field type and one to define how to use the field's value. In this
+example, ``getWithOpenCommentField`` and ``getWithOpenCommentFilter`` implement
+this functionality.
 
 .. code-block:: php
 

Resources/doc/reference/form_field_definition.rst

@@ -36,9 +36,9 @@ Example
 
 .. note::
 
-    By default, the form framework always set ``required=true`` for field. This can be an issue for
-    HTML5 browsers as they provide client side validation.
-
+    By default, the form framework always sets ``required=true`` for each
+    field. This can be an issue for HTML5 browsers as they provide client-side
+    validation.
 
 Types available
 ---------------
@@ -56,13 +56,15 @@ Types available
 - text
 - date
 
-if no type is set, the Admin class will use the one set in the doctrine mapping definition.
+If no type is set, the Admin class will use the one set in the doctrine mapping
+definition.
 
-Advanced Usage : File Management
+Advanced Usage: File Management
 --------------------------------
 
-If you want to use custom type from the Form framework you must used the ``addType`` method. (The ``add`` method uses
-the information provided by the model definition).
+If you want to use custom types from the Form framework you must use the
+``addType`` method. (The ``add`` method uses the information provided by the
+model definition).
 
 .. code-block:: php
 
@@ -90,25 +92,25 @@ the information provided by the model definition).
 
 .. note::
 
-    By setting ``type=false`` in the file definition, the Form framework will provide an instance of
-    ``UploadedFile`` for the ``Media::setBinaryContent`` method. Otherwise, the full path will be provided.
+    By setting ``type=false`` in the file definition, the Form framework will
+    provide an instance of ``UploadedFile`` for the ``Media::setBinaryContent``
+    method. Otherwise, the full path will be provided.
 
+Advanced Usage: Many-to-one
+----------------------------
 
+If you have many ``Post``s linked to one ``User``, then the ``Post`` form should
+display a ``User`` field.
 
+The AdminBundle provides 3 edit options:
 
-Advanced Usage : Many-to-one
-----------------------------
+ - ``standard``: default value, the user list is set in a select widget
+ - ``list``: the user list is set in a model where you can search and select a user
 
-If you have many ``Post`` linked to one ``User``, then the ``Post`` form should display a ``User`` field. 
-The AdminBundle provides 3 edit options :
-
- - ``standard`` : default value, the user list is set in a select widget
- - ``list`` : the user list is set in a model where you can search and select a user
- 
 In both case, you can create a new ``User`` by clicking on the "+" icon.
 
 The last option, is ``inline`` this option embed the ``User`` form into the ``Post`` Form. This option is
-great for One-to-one, or if your want to allow the user to edit the ``User`` information.
+great for one-to-one, or if your want to allow the user to edit the ``User`` information.
 
 .. code-block:: php
 
@@ -122,16 +124,17 @@ great for One-to-one, or if your want to allow the user to edit the ``User`` inf
         );
     }
 
-Advanced Usage : One-to-many
+Advanced Usage: One-to-many
 ----------------------------
 
-Let's say you have a ``Gallery`` links to some ``Media`` with a join table ``galleryHasMedias``. You
-can easily add new ``galleryHasMedias`` row by defining the different options :
-
-  - ``edit`` : ``inline|standard``, the inline mode allows you to add new rows
-  - ``inline`` : ``table|standard``, the fields are displayed into table
-  - ``sortable`` : if the model has an position field, you can enable a drag and drop sortable effect by setting ``sortable=field_name``
+Let's say you have a ``Gallery`` that links to some ``Media``s with a join table
+``galleryHasMedias``. You can easily add a new ``galleryHasMedias`` row by
+defining one of these options:
 
+  - ``edit``: ``inline|standard``, the inline mode allows you to add new rows
+  - ``inline``: ``table|standard``, the fields are displayed into table
+  - ``sortable``: if the model has a position field, you can enable a drag and
+    drop sortable effect by setting ``sortable=field_name``
 
 .. code-block:: php
 

Resources/doc/reference/installation.rst

@@ -22,7 +22,8 @@ If you are not using git, you will have to download them :
 Configuration
 -------------
   
-Next, be sure to enable the bundles in your application kernel:
+Next, be sure to enable the bundles in your autoload.php and AppKernel.php
+files:
 
 .. code-block:: php
 
@@ -47,7 +48,6 @@ Next, be sure to enable the bundles in your application kernel:
       );
   }
 
-
 The bundle also contains several routes. Import them by adding the following
 code to your application's routing file:
 
@@ -63,8 +63,10 @@ code to your application's routing file:
         type: sonata_admin
         prefix: /admin
 
-Now, install the assets of the different bundles: ``php app/console assets:install web --symlink``.
-At this point you can access to the dashboard with the url: ``http://yoursite.local/admin/dashboard``.
+Now, install the assets from the different bundles:
+``php app/console assets:install web --symlink``.
+At this point you can access to the dashboard with the url:
+``http://yoursite.local/admin/dashboard``.
 
 .. note::
 

Resources/doc/reference/list_field_definition.rst

@@ -60,7 +60,7 @@ mapping definition.
 List Actions
 ------------
 
-You can set actions for each items in list by adding in $list, the '_action' field :
+You can set actions for the list items by adding an '_action' field in $list:
 
 .. code-block:: php
 
@@ -71,10 +71,10 @@ You can set actions for each items in list by adding in $list, the '_action' fie
       )
     )
 
-Edit and delete actions are available in default configuration. You can add your own! Default template 
-file is : ``SonataAdminBundle:CRUD:list__action_[ACTION_NAME].html.twig``
-  
-But you can specify yours by setup 'template' option like :
+Edit and delete actions are enabled in the default configuration. You can add
+your own! Default template  file is: ``SonataAdminBundle:CRUD:list__action_[ACTION_NAME].html.twig``
+
+You can specify your own by setting up the 'template' option like so:
 
 .. code-block:: php
 
@@ -90,7 +90,6 @@ Advance Usage
 
 If you need a specific layout for a row cell, you can define a custom template
 
-
 .. code-block:: php
 
     class MediaAdmin extends Admin
@@ -112,4 +111,4 @@ The related template :
             <strong>{{ object.name }}</strong> <br />
             {{ object.providername}} : {{ object.width }}x{{ object.height }} <br />
         </div>
-    {% endblock %}
+    {% endblock %}

Resources/doc/reference/routing.rst

@@ -4,7 +4,7 @@ Routing
 The default routes used in the CRUD controller are accessible through the
 ``Admin`` class.
 
-The ``Admin`` class contains two routing method:
+The ``Admin`` class contains two routing methods:
 
 * ``getRoutes()``: Returns the available routes;
 * ``generateUrl($name, $options)``: Generates the related routes.
@@ -22,11 +22,10 @@ represents the route prefix.
         protected $baseRouteName = 'news_post_admin';
     }
 
-
-If no ``baseRouteName`` is defined then the Admin will pick on for you, built on
-following format : 'admin_vendor_bundlename_entityname_action'. If the Admin
-fails to find the best baseRouteName then a ``RuntimeException`` will
-be throw.
+If no ``baseRouteName`` is defined then the Admin will pick one for you, built
+in the following format: 'admin_vendor_bundlename_entityname_action'. If the
+Admin fails to find the best baseRouteName then a ``RuntimeException`` will
+be thrown.
 
 The same goes for the ``baseRoutePattern``.
 
@@ -44,10 +43,12 @@ Inside a CRUD template, a route can be generated by using the ``Admin`` class.
 Create a route
 --------------
 
-You can easily register new routes by defining them in the ``Admin`` class. Only Admin routes should be register this
-way. Of course this require to have the related action defined in the controller.
+You can easily register new routes by defining them in the ``Admin`` class.
+Only Admin routes should be registered this way. Of course this requires the
+related action to be defined in the controller.
 
-A route is always generated with the ``Admin`` context, that is why a route can be only defined by its name.
+As route is always generated with the ``Admin`` context, it can only be
+defined by its name.
 
 .. code-block:: php
 
@@ -88,4 +89,4 @@ method. This method will be used when a link is being generated.
     }
 
     // the result :
-    //   $admin->generateUrl('create') => /admin/module/create?context=default
+    //   $admin->generateUrl('create') => /admin/module/create?context=default

Resources/doc/tutorial/creating_your_first_admin_class/defining_admin_class.rst

@@ -1,15 +1,13 @@
 Defining admin class
 ====================
 
-
-The admin class contains all information required to generate the CRUD interface.
-Let's create the Post Admin class.
-
+The admin class contains all the information required to generate the CRUD
+interface. Let's create the Post Admin class.
 
 PostAdmin
 ---------
 
-By convention Admin files are set under a Admin folder.
+By convention, Admin files are located in an Admin namespace.
 
 First, you need to create an Admin/PostAdmin.php file
 
@@ -60,7 +58,7 @@ First, you need to create an Admin/PostAdmin.php file
         }
     }
 
-Secondly, register the PostAdmin class inside the DIC in your config.xml file.
+Second, register the PostAdmin class inside the DIC in your config file:
 
 .. code-block:: xml
 
@@ -72,7 +70,7 @@ Secondly, register the PostAdmin class inside the DIC in your config.xml file.
         <argument>SonataNewsBundle:PostAdmin</argument>
     </service>
 
-Or if you're using an YML configuration file,
+Or if you're using a YML configuration file:
 
 .. code-block:: yaml
 
@@ -83,10 +81,13 @@ Or if you're using an YML configuration file,
             - { name: sonata.admin, manager_type: orm, group: sonata_blog, label: post }
           arguments: [null, Sonata\NewsBundle\Entity\Post, SonataNewsBundle:PostAdmin]
 
-These is the minimal configuration required to display the entity inside the dashboard and
-interact with the CRUD interface. However, you need to create your admin Controller.
-The interface will display too many fields as some of them are not meant to be displayed.
-We'll see how we can specify the differents fields we want to use
+These is the minimal configuration required to display the entity inside the
+dashboard and interact with the CRUD interface. Following this however, you will
+need to create an admin Controller.
+
+This interface will display too many fields as some of them are not relevant to
+a general overview. Next We'll see how to specify the fields we want to use and
+how we want to use them.
 
 Tweak the PostAdmin class
 -------------------------
@@ -135,7 +136,6 @@ You can specify which field you want displayed for each action (list, form and f
 
 Now the different CRUD interfaces will look nicer!
 
-
 So same goes for the TagAdmin and CommentAdmin class.
 
 Tweak the TagAdmin class

Resources/doc/tutorial/creating_your_first_admin_class/defining_crud_controller.rst

@@ -1,17 +1,17 @@
 Defining the CRUD controller
 ============================
 
-A crud controller class is just an empty class with no methods. However, you can easily add here
-new action or overwrite the default CRUD actions.
+A crud controller class is just an empty class with no methods. However, you can
+add new actions or overwrite the default CRUD actions to suit your application.
 
 .. note::
-  
+
     The controller declaration is optional, if none is defined, then the ``AdminBundle`` will use
     the ``CRUDController``.
 
 Just create 3 files inside the Controller directory
 
-CommendAdminController
+CommentAdminController
 ~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: php
@@ -56,7 +56,7 @@ TagAdminController
 
     }
 
+When the controller class is instantiated, the admin class is attached to the
+controller.
 
-When the controller class is instanciated, the admin class is attached to the controller.
-
-Let's create the admin classes ...
+Let's create the admin classes ...

Resources/doc/tutorial/creating_your_first_admin_class/defining_entities.rst

@@ -1,9 +1,9 @@
 Defining Entities
 =================
 
-This tutorial use the verbose xml definition, the other alternative will be to use the annotation driver.
-
-
+This tutorial uses the more verbose xml format of defining entities, but any
+metadata driver will work fine. The ``AdminBundle`` simply interacts with the
+entities as provided by Doctrine.
 
 Model definition
 ----------------
@@ -259,6 +259,6 @@ Comment
 Generate getter and setter
 --------------------------
 
-start the doctrine command : php project/console doctrine:generate:entities
-
-At this point doctrine just added all required setter and getter.
+Run the doctrine command "doctrine:generate:entities" to fill in the relevant
+getter/setter methods for your new entities. This is usually accomplished by
+using the "console" application in your application directory.

Resources/doc/tutorial/creating_your_first_admin_class/defining_routing.rst

@@ -1,7 +1,7 @@
 Defining the routing
 ====================
 
-Each entity required 6 routes :
+Each entity requires 6 routes :
 
 - list
 - create
@@ -10,4 +10,5 @@ Each entity required 6 routes :
 - edit
 - delete
 
-The route information are automatically generated for you. So you can jump to the next chapitre.
+The route information is automatically generated for you, so you can jump
+straight into the next chapter.

Resources/doc/tutorial/creating_your_first_admin_class/introduction.rst

@@ -5,7 +5,7 @@ This is a tutorial & how-to for creating your first ``Admin`` classes using
 the ``AdminBundle``. In this example, we'll create the backend of
 a blog application.
 
-The tutorial will explains how to define:
+The tutorial will explain how to define:
 
 * Entities
 * The routing