Opened 7 years ago

Closed 6 years ago

Last modified 6 years ago

#8704 closed (fixed)

Improve context processor documentation

Reported by: shacker Owned by: kkubasik
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 programmerq 6 years ago.
Added entry to the FAQ

Download all attachments as: .zip

Change History (7)

comment:1 Changed 6 years ago by jacob

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

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 6 years ago by programmerq

Added entry to the FAQ

comment:2 Changed 6 years ago by programmerq

  • Has patch set
  • Triage Stage changed from Accepted to Ready for checkin

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

comment:3 Changed 6 years ago by kkubasik

  • Keywords kkmegapatch added
  • Owner changed from nobody to kkubasik

comment:4 Changed 6 years ago by gwilson

  • milestone 1.1 deleted
  • Patch needs improvement set
  • Summary changed from Global variables documentation (context processors) to Improve context processor documentation
  • Triage Stage changed from Ready for checkin to Accepted

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 6 years ago by jacob

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

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

comment:6 Changed 6 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