[#847] Various theming docs tweaks

doc/theming/static-files.rst

@@ -12,12 +12,14 @@ a plugin can make a directory of static files available to be used or linked to
 by templates. Let's add a static image file, and change the home page template
 to use our file as the promoted image on the front page.
 
-.. note::
+.. seealso::
 
-   If you're adding CSS files consider using Fanstatic instead of
-   :ref:`extra_public_paths`, to take advantage of extra features.
-   See :doc:`fanstatic`. If you're adding |javascript| modules you have to
-   use Fanstatic, see :doc:`javascript`.
+   :doc:`fanstatic`
+
+    If you're adding CSS files consider using Fanstatic instead of
+    :ref:`extra_public_paths`, to take advantage of extra features.
+    See :doc:`fanstatic`. If you're adding |javascript| modules you have to
+    use Fanstatic, see :doc:`javascript`.
 
 First, create a ``public`` directory in your extension with a
 ``promoted-image.jpg`` file in it::

doc/theming/templates.rst

@@ -71,10 +71,13 @@ Replacing a default template file
 
 Every CKAN page is generated by rendering a particular template. For each
 page of a CKAN site there's a corresponding template file. For example the
-front page is generated from the ``ckan/templates/home/index.html`` file, the
-``/about`` page is generated from ``ckan/templates/home/about.html``, the
-datasets page at ``/dataset`` is generated from
-``ckan/templates/package/search.html``, etc.
+front page is generated from the
+`ckan/templates/home/index.html <https://github.com/okfn/ckan/blob/master/ckan/templates/home/index.html>`_
+file, the ``/about`` page is generated from
+`ckan/templates/home/about.html <https://github.com/okfn/ckan/blob/master/ckan/templates/home/about.html>`_,
+the datasets page at ``/dataset`` is generated from
+`ckan/templates/package/search.html <https://github.com/okfn/ckan/blob/master/ckan/templates/package/search.html>`_,
+etc.
 
 To customize pages, our plugin needs to register its own custom template
 directory containing template files that override the default ones.
@@ -85,7 +88,8 @@ this:
 
 This new code does a few things:
 
-1. It imports CKAN's *plugins toolkit* module:
+1. It imports CKAN's :doc:`plugins toolkit </extensions/plugins-toolkit>`
+   module:
 
    .. literalinclude:: /../ckanext/example_theme/v02_empty_template/plugin.py
       :start-after: import ckan.plugins as plugins
@@ -227,28 +231,25 @@ The simplest use of an expression is to display the value of a variable, for
 example ``{{ foo }}`` in a template file will be replaced with the value of the
 variable ``foo`` when the template is rendered.
 
-.. _Pylons app_globals object: http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/glossary.html#term-app-globals
-
 CKAN makes a number of global variables available to all templates. One such
-variable is ``app_globals``, the `Pylons app_globals object`_, which can be
-used to access certain global attributes including some of the settings from
-your CKAN config file. For example, to display the value of the
-:ref:`ckan.site_title` setting from your config file you would put this code in
-any template file:
+variable is :py:data:`app_globals`, which can be used to access certain global
+attributes including some of the settings from your CKAN config file. For
+example, to display the value of the :ref:`ckan.site_title` setting from your
+config file you would put this code in any template file:
 
 .. literalinclude:: /../ckanext/example_theme/v03_jinja/templates/home/index.html
    :start-after: Jinja variable example
    :end-before: End example
 
 .. note::
 
-   Not all config settings are available to templates via ``app_globals``.
-   The :ref:`sqlalchemy.url` setting, for example, contains your database
-   password, so making that variable available to templates might be a security
-   risk.
+   Not all config settings are available to templates via
+   :py:data:`app_globals`. The :ref:`sqlalchemy.url` setting, for example,
+   contains your database password, so making that variable available to
+   templates might be a security risk.
 
    If you've added your own custom options to your config file, these will not
-   be available in ``app_globals``.
+   be available in :py:data:`app_globals`.
 
    .. todo:: Insert cross-ref to custom config options section.
 
@@ -266,7 +267,7 @@ any template file:
    If, on the other hand, you try to render an attribute of a variable that
    doesn't exist, then Jinja2 will crash. For example, this Jinja2 expression
    will crash with an
-   ``UndefinedError: 'a_variable_that_does_not_exist' is undefined``:
+   ``UndefinedError: 'a_variable_that_does_not_exist' is undefined``::
 
      {{ a_variable_that_does_not_exist.an_attribute_that_does_not_exist }}
 
@@ -422,8 +423,8 @@ stream:
    :alt: The recently changed packages activity stream.
 
 To call a template helper function we use a Jinja2 *expression* (code wrapped
-in ``{{ ... }}`` brackets), and we use the global variable ``h`` (available
-to all templates) to access the helper:
+in ``{{ ... }}`` brackets), and we use the global variable :py:data:`h`
+(available to all templates) to access the helper:
 
 .. literalinclude:: /../ckanext/example_theme/v07_helper_function/templates/home/layout1.html
    :start-after: {% block featured_group %}
@@ -479,7 +480,7 @@ as a template helper:
 
 Now that we've registered our helper function, we need to call it from our
 template. As with CKAN's default template helpers, templates access custom
-helpers via the global variable ``h``.
+helpers via the global variable :py:data:`h`.
 Edit |layout1.html| to look like this:
 
 .. literalinclude:: /../ckanext/example_theme/v08_custom_helper_function/templates/home/layout1.html