Opened 3 years ago

Closed 3 years ago

Last modified 3 years ago

#19498 closed Cleanup/optimization (fixed)

refactor authentication documentation

Reported by: ptone Owned by: nobody
Component: Documentation Version: master
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 Changed 3 years ago by ptone

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 follow-up: Changed 3 years ago by 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!

comment:3 in reply to: ↑ 2 Changed 3 years ago by ptone

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 Changed 3 years ago by ptone

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 Changed 3 years ago by Preston Holmes <preston@…>

  • Resolution set to fixed
  • Status changed from new to closed

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 Changed 3 years ago by 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.

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