Updated routing.rst to clarify and expand it

Split "Routing Definition" into two sub-sections and clarified what baseRouteName does and how all the action routes' names are generated

Listed the default routes defined by Sonata

Added note about how to see the current routes for an Admin (via the console)

Added note that removing a route stops Sonata from linking to that action

Added sub-headings to the "Removing a route" section

Cleaned up the "Default route in List Action" section

Tidied up and expanded the "Create a route" section

Resources/doc/reference/routing.rst

@@ -12,23 +12,37 @@ The ``Admin`` class contains two routing methods:
 Routing Definition
 ------------------
 
-You can set a ``baseRouteName`` property inside your ``Admin`` class, which
-represents the route prefix.
+Route names
+^^^^^^^^^^^
+
+You can set a ``baseRouteName`` property inside your ``Admin`` class. This
+represents the route prefix, to which an underscore and the action name will 
+be added to generate the actual route names. Note: this is the internal *name* 
+given to a route (it has nothing to do with the route's visible *URL*).
 
 .. code-block:: php
 
     <?php
     class PostAdmin extends Admin
     {
-        protected $baseRouteName = 'news_post_admin';
+        protected $baseRouteName = 'sonata_post';
+        // will result in routes named:
+        //   sonata_post_list
+        //   sonata_post_create
+        //   etc..
     }
 
-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.
+If no ``baseRouteName`` is defined then the Admin will generate one for you, 
+based on the following format: 'admin_vendor_bundlename_entityname' so you will have
+route names for your actions like 'admin_vendor_bundlename_entityname_list'.
+
+If the Admin fails to find a baseRouteName for your Admin class a ``RuntimeException`` 
+will be thrown with a related message.
 
-You can also use ``baseRoutePattern`` to set a custom URL for a given ``Admin`` class.
+Route patterns (URLs)
+^^^^^^^^^^^^^^^^^^^^^
+
+You can use ``baseRoutePattern`` to set a custom URL for a given ``Admin`` class.
 
 For example, to use ``http://yourdomain.com/admin/foo`` as the base URL for 
 the ``FooAdmin`` class (instead of the default of ``http://yourdomain.com/admin/vendor/bundle/foo``)
@@ -56,15 +70,21 @@ Inside a CRUD template, a route can be generated by using the ``Admin`` class.
 
     <a href="{{ admin.generateUrl('list', params|merge('page': 1) }}">List</a>
 
+Note that you do not need to provide the Admin's route prefix (baseRouteName) to 
+generate the URL, just the action name.
+
+
 Create a route
 --------------
 
-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.
+You can register new routes by defining them in your ``Admin`` class. Only Admin 
+routes should be registered this way. Of course this requires the related action 
+to be defined in the controller.
 
-As route is always generated with the ``Admin`` context, it can only be
-defined by its name.
+The routes you define in this way are generated within your Admin's context, and
+the only required parameter to ``add()`` is the action name. The second parameter
+can be used to define the URL format to append to ``baseRoutePattern``, if not set
+explicitly this defaults to the action name.
 
 .. code-block:: php
 
@@ -83,7 +103,33 @@ defined by its name.
 Removing a route
 --------------
 
-Any registered route can be easily removed.
+Extending ``Sonata\AdminBundle\Admin\Admin`` will give your Admin classes the following
+default routes:
+    
+* batch
+* create
+* delete
+* export
+* edit
+* list
+* show
+
+You can view all of the current routes defined for an Admin class by using the console to run 
+
+``php app/console sonata:admin:explain <<admin.service.name>>``
+
+for example if your Admin is called sonata.admin.foo you would run 
+
+``php app/console sonata:admin:explain sonata.admin.foo``
+
+Sonata internally checks for the existence of a route before linking to it. As a result, removing a
+route will prevent links to that action from appearing in the administrative interface. For example,
+removing the 'create' route will prevent any links to "Add new" from appearing.
+
+Removing a single route
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Any single registered route can be easily removed by name:
 
 .. code-block:: php
 
@@ -99,8 +145,11 @@ Any registered route can be easily removed.
     }
 
 
-If you want to disable all default Sonata routes except few whitelisted ones, you can use ``clearExcept()`` method.
-This method accepts an array of routes you want to keep active.
+Removing all routes except named ones
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to disable all default Sonata routes except few whitelisted ones, you can use 
+the ``clearExcept()`` method. This method accepts an array of routes you want to keep active.
 
 .. code-block:: php
 
@@ -116,6 +165,9 @@ This method accepts an array of routes you want to keep active.
         }
     }
 
+Removing all routes
+^^^^^^^^^^^^^^^^^^^
+
 If you want to remove all default routes, you can use ``clear()`` method.
 
 .. code-block:: php
@@ -132,6 +184,9 @@ If you want to remove all default routes, you can use ``clear()`` method.
         }
     }
 
+Removing routes only when an Admin is embedded
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 To prevent some routes from being available when one Admin is embedded inside another one
 (e.g. to remove the "add new" option when you embed ``TagAdmin`` within ``PostAdmin``) you 
 can use ``hasParentFieldDescription()`` to detect this case and remove the routes.
@@ -151,7 +206,6 @@ can use ``hasParentFieldDescription()`` to detect this case and remove the route
         }
     }
 
-
 Persistent parameters
 ---------------------
 
@@ -178,14 +232,15 @@ method. This method will be used when a link is being generated.
         }
     }
 
-    // the result :
-    //   $admin->generateUrl('create') => /admin/module/create?context=default
+    // the result:
+    // $admin->generateUrl('create') => /admin/module/create?context=default
 
-Default route in List Action
-----------------------------
+Changing the default route in a List Action
+-------------------------------------------
 
-Sometimes you need show entity without edit. You can choose route in addIdentifier method
-of ListMapper
+Usually the identifier column of a list action links to the edit screen. To change the 
+list action's links to point to a different action, set the ``route`` option in your call to
+``ListMapper::addIdentifier()``. For example, to link to show instead of edit:
 
 .. code-block:: php
 
@@ -195,6 +250,8 @@ of ListMapper
         public function configureListFields(ListMapper $listMapper)
         {
             $listMapper
-                ->addIdentifier('name', null, array('label' => 'name', 'route' => array('name' => 'show')));
+                ->addIdentifier('name', null, array(
+                    'route' => array('name' => 'show')
+                ));
         }
     }