From b09581394e7dd7629e71c775d1cc7160b0c26184 Mon Sep 17 00:00:00 2001 From: Luke Plant Date: Sat, 8 May 2010 14:31:20 +0000 Subject: [PATCH] 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 git-svn-id: http://code.djangoproject.com/svn/django/trunk@13135 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/Makefile | 2 +- docs/_ext/djangodocs.py | 43 +++++++++++++++++++++++++++++++++++-- docs/_static/djangodocs.css | 7 +++++- docs/_templates/layout.html | 37 +++++++++++++++++++++++++++++++ docs/topics/auth.txt | 6 +++--- 5 files changed, 88 insertions(+), 7 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index b1dfa26da04..f6a92b6835a 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -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." diff --git a/docs/_ext/djangodocs.py b/docs/_ext/djangodocs.py index aaad219b54e..efcd94d4bc8 100644 --- a/docs/_ext/djangodocs.py +++ b/docs/_ext/djangodocs.py @@ -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,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 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(); diff --git a/docs/_static/djangodocs.css b/docs/_static/djangodocs.css index a41be6d1b04..4adb8387ccc 100644 --- a/docs/_static/djangodocs.css +++ b/docs/_static/djangodocs.css @@ -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;} diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index e0e69520ad4..70e029c3acf 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -16,6 +16,43 @@ {%- endif %} {%- endmacro %} +{% block extrahead %} +{{ super() }} + + +{% endblock %} + {% block document %}
diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt index bf2d8bf6bd6..3041e39705b 100644 --- a/docs/topics/auth.txt +++ b/docs/topics/auth.txt @@ -1253,7 +1253,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 %}

Welcome, {{ user.username }}. Thanks for logging in.

@@ -1288,7 +1288,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 %}

You have permission to do something in the foo app.

@@ -1361,7 +1361,7 @@ logged-in user and his/her messages are made available in the :ref:`template context ` as the template variable ``{{ messages }}``. Here's an example of template code that displays messages: -.. code-block:: html +.. code-block:: html+django {% if messages %}