Various clean up and lots of docs

1 files changed, 39 insertions, 10 deletions

diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md
index dbb352fe..7411bd7b 100644
--- a/docs/api-guide/routers.md
+++ b/docs/api-guide/routers.md
@@ -8,20 +8,49 @@
 
 Some Web frameworks such as Rails provide functionality for automatically determining how the URLs for an application should be mapped to the logic that deals with handling incoming requests.
 
-Conversely, Django stops short of automatically generating URLs, and requires you to explicitly manage your URL configuration.
+REST framework adds support for automatic URL routing to Django, and provides you with a simple, quick and consistent way of wiring your view logic to a set of URLs.
 
-REST framework adds support for automatic URL routing, which provides you with a simple, quick and consistent way of wiring your view logic to a set of URLs.
+## Usage
 
-# API Guide
-
-Routers provide a convenient and simple shortcut for wiring up your application's URLs.
+Here's an example of a simple URL conf, that uses `DefaultRouter`.
 
     router = routers.DefaultRouter()
-    router.register('^/', APIRoot, 'api-root')
-    router.register('^users/', UserViewSet, 'user')
-    router.register('^groups/', GroupViewSet, 'group')
-    router.register('^accounts/', AccountViewSet, 'account')
+    router.register(r'users', UserViewSet, 'user')
+    router.register(r'accounts', AccountViewSet, 'account')
+    urlpatterns = router.urls
+
+# API Guide
+
+## SimpleRouter
+
+<table border=1>
+    <tr><th>URL Style</th><th>HTTP Method</th><th>Action</th><th>URL Name</th></tr>
+    <tr><td rowspan=2>{prefix}/</td><td>GET</td><td>list</td><td rowspan=2>{basename}-list</td></tr></tr>
+    <tr><td>POST</td><td>create</td></tr>
+    <tr><td rowspan=4>{prefix}/{lookup}/</td><td>GET</td><td>retrieve</td><td rowspan=4>{basename}-detail</td></tr></tr>
+    <tr><td>PUT</td><td>update</td></tr>
+    <tr><td>PATCH</td><td>partial_update</td></tr>
+    <tr><td>DELETE</td><td>destroy</td></tr>
+    <tr><td rowspan=2>{prefix}/{lookup}/{methodname}/</td><td>GET</td><td>@link decorated method</td><td rowspan=2>{basename}-{methodname}</td></tr>
+    <tr><td>POST</td><td>@action decorated method</td></tr>
+</table>
+
+## DefaultRouter
+
+<table border=1>
+    <tr><th>URL Style</th><th>HTTP Method</th><th>Action</th><th>URL Name</th></tr>
+    <tr><td>[.format]</td><td>GET</td><td>automatically generated root view</td><td>api-root</td></tr></tr>
+    <tr><td rowspan=2>{prefix}/[.format]</td><td>GET</td><td>list</td><td rowspan=2>{basename}-list</td></tr></tr>
+    <tr><td>POST</td><td>create</td></tr>
+    <tr><td rowspan=4>{prefix}/{lookup}/[.format]</td><td>GET</td><td>retrieve</td><td rowspan=4>{basename}-detail</td></tr></tr>
+    <tr><td>PUT</td><td>update</td></tr>
+    <tr><td>PATCH</td><td>partial_update</td></tr>
+    <tr><td>DELETE</td><td>destroy</td></tr>
+    <tr><td rowspan=2>{prefix}/{lookup}/{methodname}/[.format]</td><td>GET</td><td>@link decorated method</td><td rowspan=2>{basename}-{methodname}</td></tr>
+    <tr><td>POST</td><td>@action decorated method</td></tr>
+</table>
+
+# Custom Routers
 
-    urlpatterns = router.urlpatterns
 
 [cite]: http://guides.rubyonrails.org/routing.html
\ No newline at end of file