Password reset part of django.auth isn't documented

[cortex@…]

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,

[Russell Keith-Magee]

This is definitely an area where documentation could be improved.

[Russell Keith-Magee]

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

[Chris Adams]

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?

[Tim Graham]

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.

[Chris Adams]

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.

[Rik]

I created a PR for this:

​https://github.com/django/django/pull/4280

[Erik Romijn <eromijn@…>]

In eb9b7abb833a6d317e355265552d47e0d8f24af8:

Fixed #21661 -- Expanded authentication views documentation

[Erik Romijn <eromijn@…>]

In 930fc4db7b8c4f7eeca5ce55fb7b7f8529b5a52a:

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

Backport of eb9b7abb833a6d317e355265552d47e0d8f24af8 from master.

[Erik Romijn <eromijn@…>]

In 8917684c736c445b7f4bfb7225b632cc3e5d400c:

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

Backport of eb9b7abb833a6d317e355265552d47e0d8f24af8 from master.