Opened 8 years ago

Closed 7 years ago

Last modified 7 years ago

#8704 closed (fixed)

Improve context processor documentation

Reported by: shacker Owned by: Kevin Kubasik
Component: Documentation Version: master
Severity: Keywords: kkmegapatch
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: UI/UX:

Description

The answer to the common question "How do I make variables globally available to my templates?" is "context processors," which are covered at http://www.djangoproject.com/documentation/templates_python/ . But a new developer looking for an answer to this question will never find it in the docs by searching for "global" or "global variables." The documentation is there, but very difficult to find by searching on terms related to the problem. No new developer will know to search for "context processors."

Once the right section of the documentation is found, under the cryptic title "Subclassing Context: RequestContext," implementing the code samples on that page will only yield exception errors like "global name 'RequestContext' is not defined." Which means absolutely nothing (in terms of the fix) to the new Django developer. The code samples on that page should state that you need to:

from django.template import RequestContext

To promote Django acceptance, make learning the system less painful. Be specific, come up with a tagging system for the documentation to lead new developers to the right spot in the docs, and provide complete implementation details everywhere.

Attachments (1)

request_context_global.diff (871 bytes) - added by Jeff Anderson 8 years ago.
Added entry to the FAQ

Download all attachments as: .zip

Change History (7)

comment:1 Changed 8 years ago by Jacob

milestone: 1.1
Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset
Triage Stage: UnreviewedAccepted

Probably the best approach would be an entry in the FAQ -- context processors aren't just about global variables. But changing the section title might be a good idea, too.

Changed 8 years ago by Jeff Anderson

Attachment: request_context_global.diff added

Added entry to the FAQ

comment:2 Changed 8 years ago by Jeff Anderson

Has patch: set
Triage Stage: AcceptedReady for checkin

I'm no writer, but here's a FAQ entry.

comment:3 Changed 7 years ago by Kevin Kubasik

Keywords: kkmegapatch added
Owner: changed from nobody to Kevin Kubasik

comment:4 Changed 7 years ago by Gary Wilson

milestone: 1.1
Patch needs improvement: set
Summary: Global variables documentation (context processors)Improve context processor documentation
Triage Stage: Ready for checkinAccepted

Instead of a FAQ entry, I think we should instead improve the context processor documentation to better explain how and why to use them. The current section:

http://docs.djangoproject.com/en/dev/ref/templates/api/#writing-your-own-context-processors

...doesn't really say much.

I would even say that this new/revised context processor documentation should go in its own file, as the template api documentation is already very long.

comment:5 Changed 7 years ago by Jacob

Resolution: fixed
Status: newclosed

(In [10303]) A whole lotta documentation fixes: Fixes #8704, #8826, #8980, #9243, #9343, #9529,

comment:6 Changed 7 years ago by anonymous

Interesting, I was having this exact problem and the google search came up with this article, which solved the problem. The search was for: global name 'RequestContext' is not defined

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