Opened 15 months ago

Closed 3 weeks ago

Last modified 3 weeks ago

#21661 closed Cleanup/optimization (fixed)

Password reset part of django.auth isn't documented

Reported by: cortex@… Owned by: chriscauley
Component: Documentation Version: 1.6
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

Hello,

Last time I've got the chance to talk to a django core dev, he told me that an API reference isn't a suffisent documentation according to django standard. Therefor, I open a bug on the "password reset" part of contrib.auth because the only thing that you can find is a list of function documentation starting here https://docs.djangoproject.com/en/1.6/topics/auth/default/#django.contrib.auth.views.password_reset

Thing that could be add in this documentation might be:

  • a description on how you are supposed to use this/implement this in your application
  • an example urls.py with the correct "name" keyword arguments of the function url
  • an example of customisation (all of those functions accept a lot of customisation arguments, how to I use it?)
  • which default templates are used and how to overwrite them

IMO, a not very advanced django user would have greats difficulties to use those features witht the current state of the documentation and would probably not succeed. Also, those features aren't visible at all, you really need to know that they exist or have the chance to stumble upon them.

Kind regards,

Change History (13)

comment:1 Changed 15 months ago by russellm

  • Easy pickings set
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

This is definitely an area where documentation could be improved.

comment:2 Changed 15 months ago by russellm

See #21660 for some points that need to be clarified by any candidate documentation.

comment:3 Changed 14 months ago by carljm

  • Type changed from Uncategorized to Cleanup/optimization

comment:4 Changed 14 months ago by mrchrisadams

Hi there,

I've just started looking through this at Djangoweekend in Cardiff, and at the risk of bikeshedding too much, I wanted to check a few things - I'm happy to flesh this out myself, and update the topics/auth/default.txt with content as per the ticket above.

However, this looks like it would end up adding quite a substantial amount of content to the same page, for this to be clear, I'd assume I'd normally cover a full end to end user journey including:

  • requesting a reset to a password
  • receiving an email to follow a reset link
  • updating a password link
  • ending up logged in a given system

I'd conservatively estimate that I'd use a few code blocks, and a few paras of content to document this, and the page is already quite large - would a desired pull request just involve adding all this to the existing auth/topics/default.txt file, or is this better broken out onto a separate page and linked to under the "usage" section of index.txt?

comment:5 Changed 14 months ago by timo

I think a separate page could be ok if there's enough content. Note that docs/ref/contrib/admin/index.txt has instructions on how to use the password reset functionality with the admin.

comment:6 Changed 14 months ago by mrchrisadams

Hi Timo, thanks for letting me know about the reset instructions with the admin.

I think I have enough to have a stab this week at fleshing this out and submitting a PR.

comment:7 Changed 14 months ago by mrchrisadams

  • Owner changed from nobody to mrchrisadams
  • Status changed from new to assigned

comment:8 Changed 7 months ago by chriscauley

  • Owner changed from mrchrisadams to chriscauley

comment:9 Changed 3 weeks ago by rednaw

comment:10 Changed 3 weeks ago by rednaw

  • Has patch set

comment:11 Changed 3 weeks ago by Erik Romijn <eromijn@…>

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

In eb9b7abb833a6d317e355265552d47e0d8f24af8:

Fixed #21661 -- Expanded authentication views documentation

comment:12 Changed 3 weeks ago by Erik Romijn <eromijn@…>

In 930fc4db7b8c4f7eeca5ce55fb7b7f8529b5a52a:

[1.8.x] Fixed #21661 -- Expanded authentication views documentation

Backport of eb9b7abb833a6d317e355265552d47e0d8f24af8 from master.

comment:13 Changed 3 weeks ago by Erik Romijn <eromijn@…>

In 8917684c736c445b7f4bfb7225b632cc3e5d400c:

[1.7.x] Fixed #21661 -- Expanded authentication views documentation

Backport of eb9b7abb833a6d317e355265552d47e0d8f24af8 from master.

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