Merge pull request #956 from omouse/update-router-docs

#955 updated documentation for overriding `routes` attribute in Router sub-classes

docs/api-guide/routers.md

@@ -98,7 +98,19 @@ As with `SimpleRouter` the trailing slashs on the URL routes can be removed by s
 
 Implementing a custom router isn't something you'd need to do very often, but it can be useful if you have specific requirements about how the your URLs for your API are strutured.  Doing so allows you to encapsulate the URL structure in a reusable way that ensures you don't have to write your URL patterns explicitly for each new view.
 
-The simplest way to implement a custom router is to subclass one of the existing router classes.  The `.routes` attribute is used to template the URL patterns that will be mapped to each viewset. 
+The simplest way to implement a custom router is to subclass one of the existing router classes.  The `.routes` attribute is used to template the URL patterns that will be mapped to each viewset. The `.routes` attribute is a list of `Route` named tuples.
+
+The arguments to the `Route` named tuple are:
+
+* `url`: The URL to be routed. There are format arguments available, defined in `SimpleRouter.get_urls`:
+    * `prefix` - The URL prefix to use for this set of routes.
+    * `lookup` - The lookup field used to match against a single instance.
+    * `trailing_slash` - the value of `.trailing_slash`.
+* `mapping`: Mapping of HTTP method names to the object's methods
+* `name`: The name of the URL as used in `reverse` calls. There are format arguments available, defined in `SimpleRouter.get_urls`:
+    * `basename` - The base to use for the URL names that are created.
+* `initkwargs`: Any additional arguments to the view.
+    * `suffix` - reserved for identifying the viewset type, used when generating the breadcrumb links, e.g. `AccountViewSet` becomes `Account List` when `suffix='List'`.
 
 ## Example
 
@@ -109,10 +121,18 @@ The following example will only route to the `list` and `retrieve` actions, and
         A router for read-only APIs, which doesn't use trailing suffixes.
         """
         routes = [
-            (r'^{prefix}$', {'get': 'list'}, '{basename}-list'),
-            (r'^{prefix}/{lookup}$', {'get': 'retrieve'}, '{basename}-detail')
+            Route(url=r'^{prefix}$',
+                  mapping={'get': 'list'},
+                  name='{basename}-list',
+                  initkwargs={}),
+            Route(url=r'^{prefix}/{lookup}$',
+                  mapping={'get': 'retrieve'},
+                  name='{basename}-detail',
+                  initkwargs={})
         ]
 
+The `SimpleRouter` class provides another example of setting the `.routes` attribute.
+
 ## Advanced custom routers
 
 If you want to provide totally custom behavior, you can override `BaseRouter` and override the `get_urls(self)` method.  The method should insect the registered viewsets and return a list of URL patterns.  The registered prefix, viewset and basename tuples may be inspected by accessing the `self.registry` attribute.