Commit d5ed0302 authored by Luke Plant's avatar Luke Plant
Browse files

[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


git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.1.X@13137 bcc190cf-cafb-0310-a4f2-bffc1f526a37
parent e8e87e09

docs/Makefile

+1 −1
Original line number Diff line number Diff line
@@ -31,7 +31,7 @@ clean: 
	-rm -rf $(BUILDDIR)/*



html:

	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

	$(SPHINXBUILD) -b djangohtml $(ALLSPHINXOPTS) $(BUILDDIR)/html

	@echo

	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

docs/_ext/djangodocs.py

+41 −2
Original line number Diff line number Diff line
@@ -4,12 +4,28 @@ Sphinx plugins for Django documentation. 


import docutils.nodes

import docutils.transforms

try:

    import json

except ImportError:

    try:

        import simplejson as json

    except ImportError:

        try:

            from django.utils import simplejson as json

        except ImportError:

            json = None

import os

import sphinx

import sphinx.addnodes

try:

    from sphinx import builders

except ImportError:

    import sphinx.builder as builders

try:

    import sphinx.builders.html as builders_html

except ImportError:

    builders_html = builders

from sphinx.util.console import bold

import sphinx.directives

import sphinx.environment

try:
@@ -56,6 +72,7 @@ def setup(app): 
    app.add_directive('versionadded', parse_version_directive, 1, (1, 1, 1))

    app.add_directive('versionchanged', parse_version_directive, 1, (1, 1, 1))

    app.add_transform(SuppressBlockquotes)

    app.add_builder(DjangoStandaloneHTMLBuilder)



    # Monkeypatch PickleHTMLBuilder so that it doesn't die in Sphinx 0.4.2

    if sphinx.__version__ == '0.4.2':
@@ -218,7 +235,6 @@ def monkeypatch_pickle_builder(): 
        import cPickle as pickle

    except ImportError:

        import pickle

    from sphinx.util.console import bold

    

    def handle_finish(self):

        # dump the global context
@@ -248,3 +264,26 @@ def monkeypatch_pickle_builder(): 


    builders.PickleHTMLBuilder.handle_finish = handle_finish





class DjangoStandaloneHTMLBuilder(builders_html.StandaloneHTMLBuilder):

    """

    Subclass to add some extra things we need.

    """



    name = 'djangohtml'



    def finish(self):

        super(DjangoStandaloneHTMLBuilder, self).finish()

        if json is None:

            self.warn("cannot create templatebuiltins.js due to missing simplejson dependency")

            return

        self.info(bold("writing templatebuiltins.js..."))

        xrefs = self.env.reftargets.keys()

        templatebuiltins = dict([('ttags', [n for (t,n) in xrefs if t == 'ttag']),

                                 ('tfilters', [n for (t,n) in xrefs if t == 'tfilter'])])

        outfilename = os.path.join(self.outdir, "templatebuiltins.js")

        f = open(outfilename, 'wb')

        f.write('var django_template_builtins = ')

        json.dump(templatebuiltins, f)

        f.write(';\n')

        f.close();

docs/_static/djangodocs.css

+6 −1
Original line number Diff line number Diff line
@@ -99,6 +99,11 @@ dt .literal, table .literal { background:none; } 
#bd a.reference { text-decoration: none; }

#bd a.reference tt.literal { border-bottom: 1px #234f32 dotted; }



/* Restore colors of pygments hyperlinked code */

#bd .highlight .k a:link, #bd .highlight .k a:visited { color: #000000; text-decoration: none; border-bottom: 1px dotted #000000; }

#bd .highlight .nf a:link, #bd .highlight .nf a:visited { color: #990000; text-decoration: none; border-bottom: 1px dotted #990000; }





/*** notes & admonitions ***/

.note, .admonition { padding:.8em 1em .8em; margin: 1em 0; border:1px solid #94da3a; }

.admonition-title { font-weight:bold; margin-top:0 !important; margin-bottom:0 !important;}

docs/_templates/layout.html

+37 −0
Original line number Diff line number Diff line
@@ -16,6 +16,43 @@ 
  {%- endif %}

{%- endmacro %}



{% block extrahead %}

{{ super() }}

<script type="text/javascript" src="{{ pathto('templatebuiltins.js', 1) }}"></script>

<script type="text/javascript">

(function($) {

    if (!django_template_builtins) {

       // templatebuiltins.js missing, do nothing.

       return;

    }

    $(document).ready(function() {

        // Hyperlink Django template tags and filters

        var base = "{{ pathto('ref/templates/builtins') }}";

        if (base == "#") {

            // Special case for builtins.html itself

            base = "";

        }

        // Tags are keywords, class '.k'

        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {

             var tagname = $(elem).text();

             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {

                 var fragment = tagname.replace(/_/, '-');

                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");

             }

        });

        // Filters are functions, class '.nf'

        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {

             var filtername = $(elem).text();

             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {

                 var fragment = filtername.replace(/_/, '-');

                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");

             }

        });

    });

})(jQuery);

</script>

{% endblock %}



{% block document %}

  <div id="custom-doc" class="{% block bodyclass %}{{ 'yui-t6' if pagename != 'index' else '' }}{% endblock %}">

    <div id="hd">

docs/topics/auth.txt

+3 −3
Original line number Diff line number Diff line
@@ -1230,7 +1230,7 @@ currently logged-in user, either a :class:`~django.contrib.auth.models.User` 
instance or an :class:`~django.contrib.auth.models.AnonymousUser` instance, is

stored in the template variable ``{{ user }}``:



.. code-block:: html

.. code-block:: html+django



    {% if user.is_authenticated %}

        <p>Welcome, {{ user.username }}. Thanks for logging in.</p>
@@ -1265,7 +1265,7 @@ would display ``True`` if the logged-in user had the permission 


Thus, you can check permissions in template ``{% if %}`` statements:



.. code-block:: html

.. code-block:: html+django



    {% if perms.foo %}

        <p>You have permission to do something in the foo app.</p>
@@ -1333,7 +1333,7 @@ logged-in user and his/her messages are made available in the 
:ref:`template context <ref-templates-api>` as the template variable

``{{ messages }}``. Here's an example of template code that displays messages:



.. code-block:: html

.. code-block:: html+django



    {% if messages %}

    <ul>