Opened 11 years ago

Closed 11 years ago

Last modified 11 years ago

#19498 closed Cleanup/optimization (fixed)

refactor authentication documentation

Reported by: Preston Holmes Owned by: nobody
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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

Change History (6)

comment:1 by Preston Holmes, 11 years ago

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

comment:2 by Tim Graham, 11 years ago

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!

in reply to:  2 comment:3 by Preston Holmes, 11 years ago

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.

comment:4 by Preston Holmes, 11 years ago

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.

comment:5 by Preston Holmes <preston@…>, 11 years ago

Resolution: fixed
Status: newclosed

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.

comment:6 by Preston Holmes <preston@…>, 11 years ago

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.

Note: See TracTickets for help on using tickets.
Back to Top