Added some sphinx cross-reference links to the built-in template tags and…

Added some sphinx cross-reference links to the built-in template tags and filters in multiple areas of the documentation. Also fixed a few minor inconsistencies and did a little PEP8 cleanup while I was at it.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16922 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/howto/custom-template-tags.txt

@@ -199,7 +199,7 @@ passed around inside the template code:
 
       Internally, these strings are of type ``EscapeString`` or
       ``EscapeUnicode``. Generally you don't have to worry about these; they
-      exist for the implementation of the ``escape`` filter.
+      exist for the implementation of the :tfilter:`escape` filter.
 
 Template filter code falls into one of two situations:
 
@@ -501,8 +501,8 @@ safe.
 
 To make sure your template tags are thread safe, you should never store state
 information on the node itself. For example, Django provides a builtin
-``cycle`` template tag that cycles among a list of given strings each time it's
-rendered:
+:ttag:`cycle` template tag that cycles among a list of given strings each time
+it's rendered:
 
 .. code-block:: html+django
 

docs/howto/deployment/fastcgi.txt

@@ -110,7 +110,7 @@ Running a threaded server on a TCP port::
 Running a preforked server on a Unix domain socket::
 
     ./manage.py runfcgi method=prefork socket=/home/user/mysite.sock pidfile=django.pid
-    
+
 .. admonition:: Socket security
 
     Django's default umask requires that the webserver and the Django fastcgi
@@ -223,7 +223,8 @@ This is probably the most common case, if you're using Django's admin site:
 .. _mod_rewrite: http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html
 
 Django will automatically use the pre-rewrite version of the URL when
-constructing URLs with the ``{% url %}`` template tag (and similar methods).
+constructing URLs with the :ttag:`{% url %}<url>` template tag (and similar
+methods).
 
 Using mod_fcgid as alternative to mod_fastcgi
 ----------------------------------------------
@@ -409,8 +410,8 @@ Because many of these fastcgi-based solutions require rewriting the URL at
 some point inside the Web server, the path information that Django sees may not
 resemble the original URL that was passed in. This is a problem if the Django
 application is being served from under a particular prefix and you want your
-URLs from the ``{% url %}`` tag to look like the prefix, rather than the
-rewritten version, which might contain, for example, ``mysite.fcgi``.
+URLs from the :ttag:`{% url %}<url>` tag to look like the prefix, rather than
+the rewritten version, which might contain, for example, ``mysite.fcgi``.
 
 Django makes a good attempt to work out what the real script name prefix
 should be. In particular, if the Web server sets the ``SCRIPT_URL`` (specific

docs/intro/tutorial03.txt

@@ -420,9 +420,10 @@ on the object ``poll``. Failing that, it tries an attribute lookup -- which
 works, in this case. If attribute lookup had failed, it would've tried a
 list-index lookup.
 
-Method-calling happens in the ``{% for %}`` loop: ``poll.choice_set.all`` is
-interpreted as the Python code ``poll.choice_set.all()``, which returns an
-iterable of Choice objects and is suitable for use in the ``{% for %}`` tag.
+Method-calling happens in the :ttag:`{% for %}<for>` loop:
+``poll.choice_set.all`` is interpreted as the Python code
+``poll.choice_set.all()``, which returns an iterable of Choice objects and is
+suitable for use in the :ttag:`{% for %}<for>` tag.
 
 See the :doc:`template guide </topics/templates>` for more about templates.
 

docs/intro/tutorial04.txt

@@ -49,13 +49,13 @@ A quick rundown:
       data), we need to worry about Cross Site Request Forgeries.
       Thankfully, you don't have to worry too hard, because Django comes with
       a very easy-to-use system for protecting against it. In short, all POST
-      forms that are targeted at internal URLs should use the ``{% csrf_token %}``
-      template tag.
+      forms that are targeted at internal URLs should use the
+      :ttag:`{% csrf_token %}<csrf_token>` template tag.
 
-The ``{% csrf_token %}`` tag requires information from the request object, which
-is not normally accessible from within the template context. To fix this, a
-small adjustment needs to be made to the ``detail`` view, so that it looks like
-the following::
+The :ttag:`{% csrf_token %}<csrf_token>` tag requires information from the
+request object, which is not normally accessible from within the template
+context. To fix this, a small adjustment needs to be made to the ``detail``
+view, so that it looks like the following::
 
     from django.template import RequestContext
     # ...

docs/ref/contrib/admin/index.txt

@@ -1962,8 +1962,8 @@ if you specifically wanted the admin view from the admin instance named
 For more details, see the documentation on :ref:`reversing namespaced URLs
 <topics-http-reversing-url-namespaces>`.
 
-To allow easier reversing of the admin urls in templates, Django provides an 
-``admin_url`` filter which takes an action as argument:
+To allow easier reversing of the admin urls in templates, Django provides an
+``admin_urlname`` filter which takes an action as argument:
 
 .. code-block:: html+django
 
@@ -1974,5 +1974,5 @@ To allow easier reversing of the admin urls in templates, Django provides an
 
 The action in the examples above match the last part of the URL names for
 :class:`ModelAdmin` instances described above. The ``opts`` variable can be any
-object which has an ``app_label`` and ``module_name`` and is usually supplied 
+object which has an ``app_label`` and ``module_name`` and is usually supplied
 by the admin views for the current model.

docs/ref/templates/api.txt

@@ -493,8 +493,9 @@ django.core.context_processors.csrf
 
 .. versionadded:: 1.2
 
-This processor adds a token that is needed by the ``csrf_token`` template tag
-for protection against :doc:`Cross Site Request Forgeries </ref/contrib/csrf>`.
+This processor adds a token that is needed by the :ttag:`csrf_token` template
+tag for protection against :doc:`Cross Site Request Forgeries
+</ref/contrib/csrf>`.
 
 django.core.context_processors.request
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/topics/cache.txt

@@ -587,6 +587,8 @@ Here's the same thing, with ``my_view`` wrapped in ``cache_page``::
         (r'^foo/(\d{1,2})/$', cache_page(60 * 15)(my_view)),
     )
 
+.. templatetag:: cache
+
 Template fragment caching
 =========================
 

docs/topics/db/optimization.txt

@@ -225,8 +225,8 @@ It is optimal because:
  1. Since QuerySets are lazy, this does no database queries if 'display_inbox'
     is False.
 
- #. Use of ``with`` means that we store ``user.emails.all`` in a variable for
-    later use, allowing its cache to be re-used.
+ #. Use of :ttag:`with` means that we store ``user.emails.all`` in a variable
+    for later use, allowing its cache to be re-used.
 
  #. The line ``{% if emails %}`` causes ``QuerySet.__nonzero__()`` to be called,
     which causes the ``user.emails.all()`` query to be run on the database, and
@@ -236,10 +236,10 @@ It is optimal because:
  #. The use of ``{{ emails|length }}`` calls ``QuerySet.__len__()``, filling
     out the rest of the cache without doing another query.
 
- #. The ``for`` loop iterates over the already filled cache.
+ #. The :ttag:`for` loop iterates over the already filled cache.
 
 In total, this code does either one or zero database queries. The only
-deliberate optimization performed is the use of the ``with`` tag. Using
+deliberate optimization performed is the use of the :ttag:`with` tag. Using
 ``QuerySet.exists()`` or ``QuerySet.count()`` at any point would cause
 additional queries.
 

docs/topics/i18n/internationalization.txt

@@ -425,6 +425,8 @@ Translations in :doc:`Django templates </topics/templates>` uses two template
 tags and a slightly different syntax than in Python code. To give your template
 access to these tags, put ``{% load i18n %}`` toward the top of your template.
 
+.. templatetag:: trans
+
 ``trans`` template tag
 ----------------------
 
@@ -485,7 +487,7 @@ or should be used as arguments for other template tags or filters::
 .. versionchanged:: 1.3
    New keyword argument format.
 
-Contrarily to the ``trans`` tag, the ``blocktrans`` tag allows you to mark
+Contrarily to the :ttag:`trans` tag, the ``blocktrans`` tag allows you to mark
 complex sentences consisting of literals and variable content for translation
 by making use of placeholders::
 

docs/topics/templates.txt

@@ -110,8 +110,8 @@ Filters
 You can modify variables for display by using **filters**.
 
 Filters look like this: ``{{ name|lower }}``. This displays the value of the
-``{{ name }}`` variable after being filtered through the ``lower`` filter,
-which converts text to lowercase. Use a pipe (``|``) to apply a filter.
+``{{ name }}`` variable after being filtered through the :tfilter:`lower`
+filter, which converts text to lowercase. Use a pipe (``|``) to apply a filter.
 
 Filters can be "chained." The output of one filter is applied to the next.
 ``{{ text|escape|linebreaks }}`` is a common idiom for escaping text contents,
@@ -121,13 +121,13 @@ Some filters take arguments. A filter argument looks like this: ``{{
 bio|truncatewords:30 }}``. This will display the first 30 words of the ``bio``
 variable.
 
-Filter arguments that contain spaces must be quoted; for example, to join a list
-with commas and spaced you'd use ``{{ list|join:", " }}``.
+Filter arguments that contain spaces must be quoted; for example, to join a
+list with commas and spaced you'd use ``{{ list|join:", " }}``.
 
 Django provides about thirty built-in template filters. You can read all about
 them in the :ref:`built-in filter reference <ref-templates-builtins-filters>`.
-To give you a taste of what's available, here are some of the more commonly used
-template filters:
+To give you a taste of what's available, here are some of the more commonly
+used template filters:
 
     :tfilter:`default`
         If a variable is false or empty, use given default. Otherwise, use the
@@ -206,7 +206,7 @@ tags:
         In the above, if ``athlete_list`` is not empty, the number of athletes
         will be displayed by the ``{{ athlete_list|length }}`` variable.
 
-        You can also use filters and various operators in the ``if`` tag::
+        You can also use filters and various operators in the :ttag:`if` tag::
 
             {% if athlete_list|length > 1 %}
                Team: {% for athlete in athlete_list %} ... {% endfor %}
@@ -286,8 +286,8 @@ This template, which we'll call ``base.html``, defines a simple HTML skeleton
 document that you might use for a simple two-column page. It's the job of
 "child" templates to fill the empty blocks with content.
 
-In this example, the ``{% block %}`` tag defines three blocks that child
-templates can fill in. All the ``block`` tag does is to tell the template
+In this example, the :ttag:`block` tag defines three blocks that child
+templates can fill in. All the :ttag:`block` tag does is to tell the template
 engine that a child template may override those portions of the template.
 
 A child template might look like this::
@@ -303,11 +303,11 @@ A child template might look like this::
     {% endfor %}
     {% endblock %}
 
-The ``{% extends %}`` tag is the key here. It tells the template engine that
+The :ttag:`extends` tag is the key here. It tells the template engine that
 this template "extends" another template. When the template system evaluates
 this template, first it locates the parent -- in this case, "base.html".
 
-At that point, the template engine will notice the three ``{% block %}`` tags
+At that point, the template engine will notice the three :ttag:`block` tags
 in ``base.html`` and replace those blocks with the contents of the child
 template. Depending on the value of ``blog_entries``, the output might look
 like::
@@ -359,10 +359,10 @@ content areas, such as section-wide navigation.
 
 Here are some tips for working with inheritance:
 
-    * If you use ``{% extends %}`` in a template, it must be the first template
+    * If you use :ttag:`{% extends %}<extends>` in a template, it must be the first template
       tag in that template. Template inheritance won't work, otherwise.
 
-    * More ``{% block %}`` tags in your base templates are better. Remember,
+    * More :ttag:`{% block %}<block>` tags in your base templates are better. Remember,
       child templates don't have to define all parent blocks, so you can fill
       in reasonable defaults in a number of blocks, then only define the ones
       you need later. It's better to have more hooks than fewer hooks.
@@ -388,11 +388,11 @@ Here are some tips for working with inheritance:
       In larger templates, this technique helps you see which ``{% block %}``
       tags are being closed.
 
-Finally, note that you can't define multiple ``{% block %}`` tags with the same
+Finally, note that you can't define multiple :ttag:`block` tags with the same
 name in the same template. This limitation exists because a block tag works in
 "both" directions. That is, a block tag doesn't just provide a hole to fill --
 it also defines the content that fills the hole in the *parent*. If there were
-two similarly-named ``{% block %}`` tags in a template, that template's parent
+two similarly-named :ttag:`block` tags in a template, that template's parent
 wouldn't know which one of the blocks' content to use.
 
 .. _next section: #automatic-html-escaping
@@ -436,8 +436,8 @@ do potentially bad things. This type of security exploit is called a
 To avoid this problem, you have two options:
 
     * One, you can make sure to run each untrusted variable through the
-      ``escape`` filter (documented below), which converts potentially harmful
-      HTML characters to unharmful ones. This was the default solution
+      :tfilter:`escape` filter (documented below), which converts potentially
+      harmful HTML characters to unharmful ones. This was the default solution
       in Django for its first few years, but the problem is that it puts the
       onus on *you*, the developer / template author, to ensure you're escaping
       everything. It's easy to forget to escape data.
@@ -476,7 +476,8 @@ you might be using Django's template system to produce text that is *not* HTML
 For individual variables
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-To disable auto-escaping for an individual variable, use the ``safe`` filter::
+To disable auto-escaping for an individual variable, use the :tfilter:`safe`
+filter::
 
     This will be escaped: {{ data }}
     This will not be escaped: {{ data|safe }}
@@ -492,13 +493,13 @@ For template blocks
 ~~~~~~~~~~~~~~~~~~~
 
 To control auto-escaping for a template, wrap the template (or just a
-particular section of the template) in the ``autoescape`` tag, like so::
+particular section of the template) in the :ttag:`autoescape` tag, like so::
 
     {% autoescape off %}
         Hello {{ name }}
     {% endautoescape %}
 
-The ``autoescape`` tag takes either ``on`` or ``off`` as its argument. At
+The :ttag:`autoescape` tag takes either ``on`` or ``off`` as its argument. At
 times, you might want to force auto-escaping when it would otherwise be
 disabled. Here is an example template::
 
@@ -514,8 +515,8 @@ disabled. Here is an example template::
     {% endautoescape %}
 
 The auto-escaping tag passes its effect onto templates that extend the
-current one as well as templates included via the ``include`` tag, just like
-all block tags. For example::
+current one as well as templates included via the :ttag:`include` tag,
+just like all block tags. For example::
 
     # base.html
 
@@ -548,10 +549,10 @@ think about the cases in which data shouldn't be escaped, and mark data
 appropriately, so things Just Work in the template.
 
 If you're creating a template that might be used in situations where you're
-not sure whether auto-escaping is enabled, then add an ``escape`` filter to any
-variable that needs escaping. When auto-escaping is on, there's no danger of
-the ``escape`` filter *double-escaping* data -- the ``escape`` filter does not
-affect auto-escaped variables.
+not sure whether auto-escaping is enabled, then add an :tfilter:`escape` filter
+to any variable that needs escaping. When auto-escaping is on, there's no
+danger of the :tfilter:`escape` filter *double-escaping* data -- the
+:tfilter:`escape` filter does not affect auto-escaped variables.
 
 String literals and automatic escaping
 --------------------------------------
@@ -561,9 +562,9 @@ As we mentioned earlier, filter arguments can be strings::
     {{ data|default:"This is a string literal." }}
 
 All string literals are inserted **without** any automatic escaping into the
-template -- they act as if they were all passed through the ``safe`` filter.
-The reasoning behind this is that the template author is in control of what
-goes into the string literal, so they can make sure the text is correctly
+template -- they act as if they were all passed through the :tfilter:`safe`
+filter. The reasoning behind this is that the template author is in control of
+what goes into the string literal, so they can make sure the text is correctly
 escaped when the template is written.
 
 This means you would write ::