Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #14738 -- Improved crossref linking for cache settings, and fix…

…ed a few minor typos.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14676 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 25f3eda3cc306426fdd5645e5581c08050c80c05 1 parent d8c471b
authored November 22, 2010
9  docs/ref/settings.txt
@@ -169,7 +169,7 @@ caches every page that doesn't have GET or POST parameters.
169 169
 If you set the value of this setting to ``True``, you should make sure you've
170 170
 activated ``AuthenticationMiddleware``.
171 171
 
172  
-See the :doc:`cache documentation </topics/cache>` for more information.
  172
+See :doc:`/topics/cache`.
173 173
 
174 174
 .. setting:: CACHE_MIDDLEWARE_KEY_PREFIX
175 175
 
@@ -178,8 +178,9 @@ CACHE_MIDDLEWARE_KEY_PREFIX
178 178
 
179 179
 Default: ``''`` (Empty string)
180 180
 
181  
-The cache key prefix that the cache middleware should use. See
182  
-:doc:`/topics/cache`.
  181
+The cache key prefix that the cache middleware should use.
  182
+
  183
+See :doc:`/topics/cache`.
183 184
 
184 185
 .. setting:: CACHE_MIDDLEWARE_SECONDS
185 186
 
@@ -191,6 +192,8 @@ Default: ``600``
191 192
 The default number of seconds to cache a page when the caching middleware or
192 193
 ``cache_page()`` decorator is used.
193 194
 
  195
+See :doc:`/topics/cache`.
  196
+
194 197
 .. setting:: CACHE_PREFIX
195 198
 
196 199
 CACHE_PREFIX
90  docs/topics/cache.txt
@@ -31,8 +31,8 @@ explaining how this would work for a dynamically generated Web page::
31 31
 Django comes with a robust cache system that lets you save dynamic pages so
32 32
 they don't have to be calculated for each request. For convenience, Django
33 33
 offers different levels of cache granularity: You can cache the output of
34  
-specific views, you can cache only the pieces that are difficult to produce, or
35  
-you can cache your entire site.
  34
+specific views, you can cache only the pieces that are difficult to produce,
  35
+or you can cache your entire site.
36 36
 
37 37
 Django also works well with "upstream" caches, such as Squid
38 38
 (http://www.squid-cache.org/) and browser-based caches. These are the types of
@@ -47,8 +47,9 @@ where your cached data should live -- whether in a database, on the filesystem
47 47
 or directly in memory. This is an important decision that affects your cache's
48 48
 performance; yes, some cache types are faster than others.
49 49
 
50  
-Your cache preference goes in the ``CACHE_BACKEND`` setting in your settings
51  
-file. Here's an explanation of all available values for ``CACHE_BACKEND``.
  50
+Your cache preference goes in the :setting:`CACHE_BACKEND` setting in your
  51
+settings file. Here's an explanation of all available values for
  52
+:setting:`CACHE_BACKEND`.
52 53
 
53 54
 Memcached
54 55
 ---------
@@ -75,7 +76,7 @@ This is available at ftp://ftp.tummy.com/pub/python-memcached/
75 76
     a lack of maintenance on the ``cmemcache`` library itself. Support for
76 77
     ``cmemcache`` will be removed completely in Django 1.4.
77 78
 
78  
-To use Memcached with Django, set ``CACHE_BACKEND`` to
  79
+To use Memcached with Django, set :setting:`CACHE_BACKEND` to
79 80
 ``memcached://ip:port/``, where ``ip`` is the IP address of the Memcached
80 81
 daemon and ``port`` is the port on which Memcached is running.
81 82
 
@@ -87,7 +88,8 @@ One excellent feature of Memcached is its ability to share cache over multiple
87 88
 servers. This means you can run Memcached daemons on multiple machines, and the
88 89
 program will treat the group of machines as a *single* cache, without the need
89 90
 to duplicate cache values on each machine. To take advantage of this feature,
90  
-include all server addresses in ``CACHE_BACKEND``, separated by semicolons.
  91
+include all server addresses in :setting:`CACHE_BACKEND`, separated by
  92
+semicolons.
91 93
 
92 94
 In this example, the cache is shared over Memcached instances running on IP
93 95
 address 172.19.26.240 and 172.19.26.242, both on port 11211::
@@ -123,9 +125,10 @@ not already being used in your database.) This command creates a single table
123 125
 in your database that is in the proper format that Django's database-cache
124 126
 system expects.
125 127
 
126  
-Once you've created that database table, set your ``CACHE_BACKEND`` setting to
127  
-``"db://tablename"``, where ``tablename`` is the name of the database table.
128  
-In this example, the cache table's name is ``my_cache_table``::
  128
+Once you've created that database table, set your :setting:`CACHE_BACKEND`
  129
+setting to ``"db://tablename"``, where ``tablename`` is the name of the
  130
+database table. In this example, the cache table's name is
  131
+``my_cache_table``::
129 132
 
130 133
     CACHE_BACKEND = 'db://my_cache_table'
131 134
 
@@ -181,8 +184,8 @@ Filesystem caching
181 184
 ------------------
182 185
 
183 186
 To store cached items on a filesystem, use the ``"file://"`` cache type for
184  
-``CACHE_BACKEND``. For example, to store cached data in ``/var/tmp/django_cache``,
185  
-use this setting::
  187
+:setting:`CACHE_BACKEND`. For example, to store cached data in
  188
+``/var/tmp/django_cache``, use this setting::
186 189
 
187 190
     CACHE_BACKEND = 'file:///var/tmp/django_cache'
188 191
 
@@ -212,8 +215,8 @@ Local-memory caching
212 215
 
213 216
 If you want the speed advantages of in-memory caching but don't have the
214 217
 capability of running Memcached, consider the local-memory cache backend. This
215  
-cache is multi-process and thread-safe. To use it, set ``CACHE_BACKEND`` to
216  
-``"locmem://"``. For example::
  218
+cache is multi-process and thread-safe. To use it, set :setting:`CACHE_BACKEND`
  219
+to ``"locmem://"``. For example::
217 220
 
218 221
     CACHE_BACKEND = 'locmem://'
219 222
 
@@ -231,7 +234,7 @@ just implements the cache interface without doing anything.
231 234
 This is useful if you have a production site that uses heavy-duty caching in
232 235
 various places but a development/test environment where you don't want to cache
233 236
 and don't want to have to change your code to special-case the latter. To
234  
-activate dummy caching, set ``CACHE_BACKEND`` like so::
  237
+activate dummy caching, set :setting:`CACHE_BACKEND` like so::
235 238
 
236 239
     CACHE_BACKEND = 'dummy://'
237 240
 
@@ -243,7 +246,7 @@ Using a custom cache backend
243 246
 While Django includes support for a number of cache backends out-of-the-box,
244 247
 sometimes you might want to use a customized cache backend. To use an external
245 248
 cache backend with Django, use a Python import path as the scheme portion (the
246  
-part before the initial colon) of the ``CACHE_BACKEND`` URI, like so::
  249
+part before the initial colon) of the :setting:`CACHE_BACKEND` URI, like so::
247 250
 
248 251
     CACHE_BACKEND = 'path.to.backend://'
249 252
 
@@ -259,7 +262,7 @@ CACHE_BACKEND arguments
259 262
 -----------------------
260 263
 
261 264
 Each cache backend may take arguments. They're given in query-string style on
262  
-the ``CACHE_BACKEND`` setting. Valid arguments are as follows:
  265
+the :setting:`CACHE_BACKEND` setting. Valid arguments are as follows:
263 266
 
264 267
     * ``timeout``: The default timeout, in seconds, to use for the cache.
265 268
       This argument defaults to 300 seconds (5 minutes).
@@ -315,22 +318,23 @@ entire site. You'll need to add
315 318
 
316 319
 Then, add the following required settings to your Django settings file:
317 320
 
318  
-* ``CACHE_MIDDLEWARE_SECONDS`` -- The number of seconds each page should be
319  
-  cached.
320  
-* ``CACHE_MIDDLEWARE_KEY_PREFIX`` -- If the cache is shared across multiple
321  
-  sites using the same Django installation, set this to the name of the site,
322  
-  or some other string that is unique to this Django instance, to prevent key
323  
-  collisions. Use an empty string if you don't care.
  321
+* :setting:`CACHE_MIDDLEWARE_SECONDS` -- The number of seconds each page should
  322
+  be cached.
  323
+* :setting:`CACHE_MIDDLEWARE_KEY_PREFIX` -- If the cache is shared across
  324
+  multiple sites using the same Django installation, set this to the name of
  325
+  the site, or some other string that is unique to this Django instance, to
  326
+  prevent key collisions. Use an empty string if you don't care.
324 327
 
325 328
 The cache middleware caches every page that doesn't have GET or POST
326  
-parameters. Optionally, if the ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting is
327  
-``True``, only anonymous requests (i.e., not those made by a logged-in user)
328  
-will be cached. This is a simple and effective way of disabling caching for any
329  
-user-specific pages (include Django's admin interface). Note that if you use
330  
-``CACHE_MIDDLEWARE_ANONYMOUS_ONLY``, you should make sure you've activated
331  
-``AuthenticationMiddleware``. The cache middleware expects that a HEAD request
332  
-is answered with the same response headers exactly like the corresponding GET
333  
-request, in that case it could return cached GET response for HEAD request.
  329
+parameters. Optionally, if the :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY`
  330
+setting is ``True``, only anonymous requests (i.e., not those made by a
  331
+logged-in user) will be cached. This is a simple and effective way of disabling
  332
+caching for any user-specific pages (include Django's admin interface). Note
  333
+that if you use :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY`, you should make
  334
+sure you've activated ``AuthenticationMiddleware``. The cache middleware
  335
+expects that a HEAD request is answered with the same response headers as
  336
+the corresponding GET request; in which case it can return a cached GET
  337
+response for HEAD request.
334 338
 
335 339
 Additionally, the cache middleware automatically sets a few headers in each
336 340
 ``HttpResponse``:
@@ -339,10 +343,10 @@ Additionally, the cache middleware automatically sets a few headers in each
339 343
       (uncached) version of the page is requested.
340 344
 
341 345
     * Sets the ``Expires`` header to the current date/time plus the defined
342  
-      ``CACHE_MIDDLEWARE_SECONDS``.
  346
+      :setting:`CACHE_MIDDLEWARE_SECONDS`.
343 347
 
344 348
     * Sets the ``Cache-Control`` header to give a max age for the page --
345  
-      again, from the ``CACHE_MIDDLEWARE_SECONDS`` setting.
  349
+      again, from the :setting:`CACHE_MIDDLEWARE_SECONDS` setting.
346 350
 
347 351
 See :doc:`/topics/http/middleware` for more on middleware.
348 352
 
@@ -350,7 +354,7 @@ See :doc:`/topics/http/middleware` for more on middleware.
350 354
 
351 355
 If a view sets its own cache expiry time (i.e. it has a ``max-age`` section in
352 356
 its ``Cache-Control`` header) then the page will be cached until the expiry
353  
-time, rather than ``CACHE_MIDDLEWARE_SECONDS``. Using the decorators in
  357
+time, rather than :setting:`CACHE_MIDDLEWARE_SECONDS`. Using the decorators in
354 358
 ``django.views.decorators.cache`` you can easily set a view's expiry time
355 359
 (using the ``cache_control`` decorator) or disable caching for a view (using
356 360
 the ``never_cache`` decorator). See the `using other headers`__ section for
@@ -373,6 +377,8 @@ __ `Controlling cache: Using other headers`_
373 377
 The per-view cache
374 378
 ==================
375 379
 
  380
+.. function ``django.views.decorators.cache.cache_page``
  381
+
376 382
 A more granular way to use the caching framework is by caching the output of
377 383
 individual views. ``django.views.decorators.cache`` defines a ``cache_page``
378 384
 decorator that will automatically cache the view's response for you. It's easy
@@ -402,9 +408,9 @@ then requests to ``/foo/1/`` and ``/foo/23/`` will be cached separately, as
402 408
 you may expect. But once a particular URL (e.g., ``/foo/23/``) has been
403 409
 requested, subsequent requests to that URL will use the cache.
404 410
 
405  
-``cache_page`` can also take an optional keyword argument, ``key_prefix``, which
406  
-works in the same way as the ``CACHE_MIDDLEWARE_KEY_PREFIX`` setting for the
407  
-middleware.  It can be used like this::
  411
+``cache_page`` can also take an optional keyword argument, ``key_prefix``,
  412
+which works in the same way as the :setting:`CACHE_MIDDLEWARE_KEY_PREFIX`
  413
+setting for the middleware.  It can be used like this::
408 414
 
409 415
     @cache_page(60 * 15, key_prefix="site1")
410 416
     def my_view(request):
@@ -529,7 +535,7 @@ can be pickled; refer to the Python documentation for more information about
529 535
 pickling.)
530 536
 
531 537
 The cache module, ``django.core.cache``, has a ``cache`` object that's
532  
-automatically created from the ``CACHE_BACKEND`` setting::
  538
+automatically created from the :setting:`CACHE_BACKEND` setting::
533 539
 
534 540
     >>> from django.core.cache import cache
535 541
 
@@ -540,8 +546,8 @@ The basic interface is ``set(key, value, timeout)`` and ``get(key)``::
540 546
     'hello, world!'
541 547
 
542 548
 The ``timeout`` argument is optional and defaults to the ``timeout``
543  
-argument in the ``CACHE_BACKEND`` setting (explained above). It's the number of
544  
-seconds the value should be stored in the cache.
  549
+argument in the :setting:`CACHE_BACKEND` setting (explained above). It's the
  550
+number of seconds the value should be stored in the cache.
545 551
 
546 552
 If the object doesn't exist in the cache, ``cache.get()`` returns ``None``::
547 553
 
@@ -957,7 +963,7 @@ Here's a full list:
957 963
 For explanation of Cache-Control HTTP directives, see the `Cache-Control spec`_.
958 964
 
959 965
 (Note that the caching middleware already sets the cache header's max-age with
960  
-the value of the ``CACHE_MIDDLEWARE_SETTINGS`` setting. If you use a custom
  966
+the value of the :setting:`CACHE_MIDDLEWARE_SETTINGS` setting. If you use a custom
961 967
 ``max_age`` in a ``cache_control`` decorator, the decorator will take
962 968
 precedence, and the header values will be merged correctly.)
963 969
 
@@ -984,14 +990,14 @@ site's performance:
984 990
       modern browsers to conditionally GET responses based on the ``ETag``
985 991
       and ``Last-Modified`` headers.
986 992
 
987  
-    * ``django.middleware.gzip.GZipMiddleware`` compresses responses for all
  993
+    * :class:`django.middleware.gzip.GZipMiddleware` compresses responses for all
988 994
       moderns browsers, saving bandwidth and transfer time.
989 995
 
990 996
 Order of MIDDLEWARE_CLASSES
991 997
 ===========================
992 998
 
993 999
 If you use caching middleware, it's important to put each half in the right
994  
-place within the ``MIDDLEWARE_CLASSES`` setting. That's because the cache
  1000
+place within the :setting:`MIDDLEWARE_CLASSES` setting. That's because the cache
995 1001
 middleware needs to know which headers by which to vary the cache storage.
996 1002
 Middleware always adds something to the ``Vary`` response header when it can.
997 1003
 

0 notes on commit 25f3eda

Please sign in to comment.
Something went wrong with that request. Please try again.