Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

[1.1.X] Added hyperlinks for builtin template tags and filters to cod…

…e 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
  • Loading branch information...
commit d5ed0302289db2a8b64ebd29ca1081dab364d1ee 1 parent e8e87e0
Luke Plant spookylukey authored
2  docs/Makefile
View
@@ -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."
43 docs/_ext/djangodocs.py
View
@@ -4,12 +4,28 @@
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,7 +72,8 @@ 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':
monkeypatch_pickle_builder()
@@ -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 handle_finish(self):
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();
7 docs/_static/djangodocs.css
View
@@ -98,7 +98,12 @@ pre { font-size:small; background:#E0FFB8; border:1px solid #94da3a; border-widt
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;}
37 docs/_templates/layout.html
View
@@ -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">
6 docs/topics/auth.txt
View
@@ -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>
Please sign in to comment.
Something went wrong with that request. Please try again.