[Django] #21661: Password reset part of django.auth isn't documented
Django
-------------------------------+--------------------
Reporter: cortex@… | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.6
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+--------------------
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,
--
Ticket URL: <https://code.djangoproject.com/ticket/21661>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: cortex@… | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.6
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+------------------------------------
Changes (by russellm):
* needs_better_patch: => 0
* stage: Unreviewed => Accepted
* easy: 0 => 1
* needs_tests: => 0
* needs_docs: => 0
Comment:
This is definitely an area where documentation could be improved.
--
Ticket URL: <https://code.djangoproject.com/ticket/21661#comment:1>
Django
Reporter: cortex@… | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.6
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+------------------------------------
Comment (by russellm):
See #21660 for some points that need to be clarified by any candidate
documentation.
--
Ticket URL: <https://code.djangoproject.com/ticket/21661#comment:2>
Django
Reporter: cortex@… | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by carljm):
* type: Uncategorized => Cleanup/optimization
--
Ticket URL: <https://code.djangoproject.com/ticket/21661#comment:3>
Django
Reporter: cortex@… | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (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`?
--
Ticket URL: <https://code.djangoproject.com/ticket/21661#comment:4>
Django
Reporter: cortex@… | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (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.
--
Ticket URL: <https://code.djangoproject.com/ticket/21661#comment:5>
Django
Reporter: cortex@… | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (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.
--
Ticket URL: <https://code.djangoproject.com/ticket/21661#comment:6>
Django
Reporter: cortex@… | Owner:
Type: | mrchrisadams
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.6
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by mrchrisadams):
* owner: nobody => mrchrisadams
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/21661#comment:7>
Django
Reporter: cortex@… | Owner:
Type: | chriscauley
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.6
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* owner: mrchrisadams => chriscauley
--
Ticket URL: <https://code.djangoproject.com/ticket/21661#comment:8>
Django
Reporter: cortex@… | Owner:
Type: | chriscauley
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by rednaw):
I created a PR for this:
https://github.com/django/django/pull/4280
--
Ticket URL: <https://code.djangoproject.com/ticket/21661#comment:9>
Django
Reporter: cortex@… | Owner:
Type: | chriscauley
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* has_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/21661#comment:10>
Django
Reporter: cortex@… | Owner:
Type: | chriscauley
Component: Documentation | Version: 1.6
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"eb9b7abb833a6d317e355265552d47e0d8f24af8"]:
{{{
#!CommitTicketReference repository=""
revision="eb9b7abb833a6d317e355265552d47e0d8f24af8"
Fixed #21661 -- Expanded authentication views documentation
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/21661#comment:11>
Django
Reporter: cortex@… | Owner:
Type: | chriscauley
Cleanup/optimization | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Erik Romijn <eromijn@…>):
In [changeset:"930fc4db7b8c4f7eeca5ce55fb7b7f8529b5a52a"]:
{{{
#!CommitTicketReference repository=""
revision="930fc4db7b8c4f7eeca5ce55fb7b7f8529b5a52a"
[1.8.x] Fixed #21661 -- Expanded authentication views documentation
Backport of eb9b7abb833a6d317e355265552d47e0d8f24af8 from master.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/21661#comment:12>
Django
Reporter: cortex@… | Owner:
Type: | chriscauley
Cleanup/optimization | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Erik Romijn <eromijn@…>):
In [changeset:"8917684c736c445b7f4bfb7225b632cc3e5d400c"]:
{{{
#!CommitTicketReference repository=""
revision="8917684c736c445b7f4bfb7225b632cc3e5d400c"
[1.7.x] Fixed #21661 -- Expanded authentication views documentation
Backport of eb9b7abb833a6d317e355265552d47e0d8f24af8 from master.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/21661#comment:13>