Docs tweak.

1 files changed, 23 insertions, 3 deletions

diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md
index 38cf6a7d..9d6b4c60 100644
--- a/docs/api-guide/authentication.md
+++ b/docs/api-guide/authentication.md
@@ -140,10 +140,14 @@ Unauthenticated responses that are denied permission will result in an `HTTP 401
 
     WWW-Authenticate: Token
 
+---
+
 **Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https` only.
 
 ---
 
+#### Generating Tokens
+
 If you want every user to have an automatically generated Token, you can simply catch the User's `post_save` signal.
 
     @receiver(post_save, sender=User)
@@ -159,8 +163,7 @@ If you've already created some users, you can generate tokens for all existing u
     for user in User.objects.all():
         Token.objects.get_or_create(user=user)
 
-When using `TokenAuthentication`, you may want to provide a mechanism for clients to obtain a token given the username and password. 
-REST framework provides a built-in view to provide this behavior.  To use it, add the `obtain_auth_token` view to your URLconf:
+When using `TokenAuthentication`, you may want to provide a mechanism for clients to obtain a token given the username and password.  REST framework provides a built-in view to provide this behavior.  To use it, add the `obtain_auth_token` view to your URLconf:
 
     urlpatterns += patterns('',
         url(r'^api-token-auth/', 'rest_framework.authtoken.views.obtain_auth_token')
@@ -174,7 +177,22 @@ The `obtain_auth_token` view will return a JSON response when valid `username` a
 
 Note that the default `obtain_auth_token` view explicitly uses JSON requests and responses, rather than using default renderer and parser classes in your settings.  If you need a customized version of the `obtain_auth_token` view, you can do so by overriding the `ObtainAuthToken` view class, and using that in your url conf instead.
 
-**Note:** If you are using `rest_framework.authtoken` with a custom Django user model and South. you have to insert a `needed_by = (('authtoken', '0001_initial'),)` to your user migration.
+#### Custom user models
+
+The `rest_framework.authtoken` app includes a south migration that will create the authtoken table.   If you're using a [custom user model][custom-user-model] you'll need to make sure that any initial migration that creates the user table runs before the authtoken table is created.
+
+You can do so by inserting a `needed_by` attribute in your user migration:
+
+    class Migration:
+
+        needed_by = (
+            ('authtoken', '0001_initial'),
+        )
+        
+        def forwards(self):
+            ...
+
+For more details, see the [south documentation on dependancies][south-dependancies].
 
 ## SessionAuthentication
 
@@ -240,5 +258,7 @@ HTTP digest authentication is a widely implemented scheme that was intended to r
 [throttling]: throttling.md
 [csrf-ajax]: https://docs.djangoproject.com/en/dev/ref/contrib/csrf/#ajax
 [mod_wsgi_official]: http://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIPassAuthorization
+[custom-user-model]: https://docs.djangoproject.com/en/dev/topics/auth/customizing/#specifying-a-custom-user-model
+[south-dependancies]: http://south.readthedocs.org/en/latest/dependencies.html
 [juanriaza]: https://github.com/juanriaza
 [djangorestframework-digestauth]: https://github.com/juanriaza/django-rest-framework-digestauth