refactor authentication documentation

[Preston Holmes]

Authentication is a feature that has had a lot added to it over time. As features are added, the single auth.txt topic doc has grown to an unwieldy size.

Users are faced with basic and advanced concepts all jumbled together, and certain related things were no longer grouped in a useful way.

With the addition of custom users - I wanted to try and get this refactored.

I've split the single doc into the following:

• topic intro
• default auth system - most of the content on using stock system
• API reference - model, backend, and signal reference
• customizing - backends, custom permissions, extending and replacing user model etc
• passwords - all the details that relate to storage mechanism and alternate hashing algos etc

There is one 1.6 item that will need to be removed before a backport

[Preston Holmes]

The pull request is here:
​https://github.com/django/django/pull/603

A render of the docs (because docs don't diff all that well)

​http://ptone.com/temp/auth-docs/topics/auth/index.html

[Tim Graham]

Nice, Preston. I had some trouble reviewing this since the patch no longer applies cleanly, but I left a few comments on the PR. Also some links don't work in topics/auth/index.html (e.g. "Working with User objects"). I'll be happy to give it another pass after these fixes. Thank-you!

[Preston Holmes]

Replying to timo:

Nice, Preston. I had some trouble reviewing this since the patch no longer applies cleanly, but I left a few comments on the PR. Also some links don't work in topics/auth/index.html (e.g. "Working with User objects"). I'll be happy to give it another pass after these fixes. Thank-you!

OK - I dug a bit and better understand the different types of sphinx links and I think I've got them sorted out (ran a link checker tool to confirm)- ran spell check and found a few old and a few new errors. Ran a separate link checker program to make sure that all internal links work.

I've updated my rendered output copy - along with the PR. I'm happy to add polish anywhere you can suggest some more attention is needed.

[Preston Holmes]

also just to note here that in addition to the one section that is 1.6 only that will need to be pulled for the backport, there is still the original auth.txt in the /topics dir - that I'm keeping there till merge as the way to track any changes made to it on master.

[Preston Holmes <preston@…>]

In 11ded967c443087487f3872aafd86842608b4c64:

Fixed #19498 -- refactored auth documentation

The auth doc was a single page which had grown unwieldy.
This refactor split and grouped the content into sub-topics.
Additional corrections and cleanups were made along the way.

[Preston Holmes <preston@…>]

In 8d1b1902488855e56c93f66d5a30b3ec746ff183:

[1.5.x] Fixed #19498 -- refactored auth documentation

The auth doc was a single page which had grown unwieldy.
This refactor split and grouped the content into sub-topics.
Additional corrections and cleanups were made along the way.