csrf_token not clear in User Authentication docs

[Andriy Drozdyuk]

Someone please add an explanation as to why the {% csrf_token %} is present in the User Authentication docs example HTML template:
​http://docs.djangoproject.com/en/dev/topics/auth/#django.contrib.auth.views.login

Right now it seems like "wth"? Where did that come from! Almost looks like an error.

Please include explanation of what the tags means (or at least link to the tag info page) and why it should be included in the template.

[Gabriel Hurley]

Adds info on csrf_token ahead of the form in question.

[Gabriel Hurley]

Added a patch that adds info on the csrf_token and a link to upgrading instructions ahead of the form in question so it won't surprise people (as reported in this ticket).

[Luke Plant]

I think I disagree with Russell on this one. I'm kind of loathe to clutter up the auth documentation with notes about what the CSRF tag does, for the following reasons:

• Adding documentation is always a balance - too much information about irrelevant things can really spoil the usefulness of docs.
• If we add an explanation here, we need to add it every place in the docs (there are a few others already).
• For existing developers, if they've read the release notes they'll know what the tag does.
• For new developers, if they've read the tutorial they'll know what the tag does (or at least have some vague idea why it is there).
• If developers see something like a template tag they don't understand, aren't they capable of looking it up in the template tag docs? We have this nice little search box...

I think the reaction of the reporter is over the top given these considerations. Ideally I'd like all template tags in code blocks to be hyperlinked to the docs for them, but from my initial investigations I don't think this would be easy.

[Andriy Drozdyuk]

How is my reaction "over the top"? A term is used in documentation that is never introduced first. There is even NO link leading to an explanation.
I still don't know what it does. And I don't consider myself a newbie user of django (granted I am not a django developer - but the manual is not for developers is it?)

I think you are not taking the feedback I am providing to you seriously here, but rather dismissing it as a "user error". But django docs are usually pretty good at explaining everything to you on the spot, without making you hunt for things (think msdn).

[Luke Plant]

Well, what is introduced 'first' depends on the order you read the documentation, doesn't it? And you are allowed to read it in any order. We cannot link to everything at every point, so we have an assumed order - we assume the user has at least read the tutorial, and has read the release notes for their current version if they started with Django a long time ago. With those assumptions, the tag has indeed been explained 'first'. You could have the same reaction about most of the other things in the example, like block and extends, which are equally mysterious if you haven't come across them before.

Also, the example code is presented as a block of code that can be copy-pasted into your template as a starting point. For that sort of thing, it is kind of besides the point to explain everything in it.

I am taking your feedback seriously, but there is a balance to strike, that's what I'm saying. I am surprised that you still don't know what the tag does. Have you tried to find out? Have you read the release notes for 1.2/trunk? If you are choosing to use trunk, and therefore are following trunk docs (and they are clearly labelled as such), then there is an additional burden on you as a developer to stay on top of recent changes - by reading the notes for trunk, for instance, or by taking some initiative to fill in gaps in your knowledge.

I'm also saying that by your argument we'd have to add the exact same patch to ref/contrib/formtools/form-wizard.txt and topics/i18n/internationalization.txt. Once you do that, you really start to question if that is the right approach.

Note I haven't changed the status of the bug because another core committer disagrees with me. Only if Russell changes his mind will the bug be closed as WONTFIX or whatever.

[Russell Keith-Magee]

In retrospect, I concur with Luke. but it's well documented as a standalone tag, in the release/upgrading notes, and in the tutorial. I don't think it's unreasonable to suggest that readers should have seen those documents before they see the auth topic guide; or if they haven't, that they should be able hunt down the appropriate reference to find out what the tag does. If you put csrf_token into the search field for the docs, the first result is extremely relevant.

As a case in point - the template sample doesn't describe how the {% url %} tag works, either; that doesn't mean we should include a pointer to how the {% url %} tag works.

I also agree with Luke that it would be good to have the tag itself act as a hyperlink to its own documentation, but I don't know how we could implement that within Sphinx.

[Luke Plant]

(In [13135]) Added hyperlinks for builtin template tags and filters to code samples in docs.

Implemented in javascript because doing it 'properly' is pretty much impossible with Sphinx and Pygments.

Refs #12249

[Luke Plant]

(In [13137]) [1.1.X] Added hyperlinks for builtin template tags and filters to code samples in docs.

Implemented in javascript because doing it 'properly' is pretty much impossible with Sphinx and Pygments.

Refs #12249

Backport of [13135] from trunk

[Jacob]

Milestone 1.2 deleted