A WIP refactor of auth docs - this is just a draft rough reorg - much rewriting would also be involved

current.md

• /topics/auth.txt
  • Overview
  • Installation
  • Users
    • API reference
      • Fields
      • Methods
      • Manager functions
    • Basic usage
      • Creating users
      • Changing passwords
    • How Django stores passwords
      • Using bcrypt with Django
      • Increasing the work factor
      • Password upgrading
    • Anonymous users
    • Creating superusers
    • Storing additional information about users
    • Adding UserProfile fields to the admin
  • Authentication in Web requests
  • How to log a user in
  • Manually managing a user’s password
  • How to log a user out
  • Login and logout signals
  • Limiting access to logged-in users
    • The raw way
    • The login_required decorator
  • Other built-in views
  • Helper functions
  • Built-in forms
  • Limiting access to logged-in users that pass a test
    • The permission_required decorator
  • Applying permissions to generic views
  • Permissions
    • Default permissions
    • Custom permissions
    • API reference
      • Fields
      • Methods
    • Programmatically creating permissions
  • Authentication data in templates
    • Users
    • Permissions
  • Groups
    • API reference
      • Fields
  • Customizing the User model
    • Referencing the User model
    • Specifying a custom User model
      • Extending Django’s default User
      • Custom users and the built-in auth forms
      • Custom users and django.contrib.admin
      • Custom users and Proxy models
    • A full example
  • Other authentication sources
    • Specifying authentication backends
    • Writing an authentication backend
    • Handling authorization in custom backends
      • Authorization for anonymous users
      • Authorization for inactive users
      • Handling object permissions

proposed.md

• topics/auth/
  • Overview (index.txt)
    • Installation
  • Using Django's Default implementation
    • The User object
    • Creating users
    • Creating superusers
    • Changing passwords
    • Permissions
      • Default permissions
      • Programmatically creating permissions
    • Authentication in Web requests
      • How to log a user in
      • How to log a user out
      • Limiting access to logged-in users
        • The raw way
        • The login_required decorator
        • Limiting access to logged-in users that pass a test
          • The permission_required decorator
        • Applying permissions to generic views
      • Other built-in views
      • Built-in forms
      • Authentication data in templates
        • Users
        • Permissions
    • Managing Users in the admin
      • Creating users
      • changing passwords
      • Displaying related data (Adding UserProfile fields to the admin)
      • Groups
      • permissions
    • Helper functions
    • extending builtin authentication vs customizing - need a clearer semantic difference
      • Storing additional information about users
        • using 1:1 fields
          • brief deprecated get_profile
        • proxy model?
  • API Reference
    • Users
      • Fields
      • Methods
      • Manager functions
    • Anonymous users
    • Groups
    • Permissions
    • Backends
    • Login and logout signals
  • Passwords
    • How Django stores passwords
      • Using bcrypt with Django
      • Increasing the work factor
      • Password upgrading
    • Manually managing a user’s password
  • Customizing authentication
    • Other authentication sources
      • Specifying authentication backends
      • Writing an authentication backend
      • Handling authorization in custom backends
        • Authorization for anonymous users
        • Authorization for inactive users
        • Handling object permissions
    • Custom permissions
    • Customizing the User model
      • Referencing the User model
      • Specifying a custom User model
        • Extending Django’s default User
        • Custom users and the built-in auth forms
        • Custom users and django.contrib.admin
        • Custom users and Proxy models
      • A full example