More templating docs.

3 files changed, 168 insertions, 41 deletions

diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst
index 98f5485e..03fbdeea 100644
--- a/doc/markup/misc.rst
+++ b/doc/markup/misc.rst
@@ -3,6 +3,8 @@
 Miscellaneous markup
 ====================
 
+.. _metadata::
+
 File-wide metadata
 ------------------
 
diff --git a/doc/templating.rst b/doc/templating.rst
index 20c61ce0..2ee449aa 100644
--- a/doc/templating.rst
+++ b/doc/templating.rst
@@ -1,3 +1,5 @@
+.. highlight:: html+jinja
+
 .. _templating:
 
 Templating
@@ -37,27 +39,26 @@ template, customizing it while also keeping the changes at a minimum.
 
 To customize the output of your documentation you can override all the templates
 (both the layout templates and the child templates) by adding files with the
-same name as the original filename into the template directory of the folder the
-Sphinx quickstart generated for you.
+same name as the original filename into the template directory of the structure
+the Sphinx quickstart generated for you.
 
 Sphinx will look for templates in the folders of :confval:`templates_path`
 first, and if it can't find the template it's looking for there, it falls back
-to the builtin templates that come with Sphinx.
+to the selected theme's templates.
 
 A template contains **variables**, which are replaced with values when the
 template is evaluated, **tags**, which control the logic of the template and
 **blocks** which are used for template inheritance.
 
-Sphinx provides base templates with a couple of blocks it will fill with data.
-The default templates are located in the :file:`templates` folder of the Sphinx
-installation directory.  Templates with the same name in the
-:confval:`templates_path` override templates located in the builtin folder.
+Sphinx' *basic* theme provides base templates with a couple of blocks it will
+fill with data.  These are located in the :file:`themes/basic` subdirectory of
+the Sphinx installation directory, and used by all builtin Sphinx themes.
+Templates with the same name in the :confval:`templates_path` override templates
+supplied by the selected theme.
 
 For example, to add a new link to the template area containing related links all
 you have to do is to add a new template called ``layout.html`` with the
-following contents:
-
-.. sourcecode:: html+jinja
+following contents::
 
     {% extends "!layout.html" %}
     {% block rootrellink %}
@@ -65,16 +66,24 @@ following contents:
         {{ super() }}
     {% endblock %}
 
-By prefixing the name of the extended template with an exclamation mark, Sphinx
-will load the builtin layout template.  If you override a block, you should call
-``{{ super() }}`` somewhere to render the block's content in the extended
-template -- unless you don't want that content to show up.
+By prefixing the name of the overridden template with an exclamation mark,
+Sphinx will load the layout template from the underlying HTML theme.
+
+**Important**: If you override a block, call ``{{ super() }}`` somewhere to
+render the block's content in the extended template -- unless you don't want
+that content to show up.
+
 
+Working the the builtin templates
+---------------------------------
+
+The builtin **basic** theme supplies the templates that all builtin Sphinx
+themes are based on.  It has the following elements you can override or use:
 
 Blocks
 ~~~~~~
 
-The following blocks exist in the ``layout`` template:
+The following blocks exist in the ``layout.html`` template:
 
 `doctype`
     The doctype of the output format.  By default this is XHTML 1.0 Transitional
@@ -92,11 +101,11 @@ The following blocks exist in the ``layout`` template:
     add references to JavaScript or extra CSS files.
 
 `relbar1` / `relbar2`
-    This block contains the list of related links (the parent documents on the
-    left, and the links to index, modules etc. on the right).  `relbar1` appears
-    before the document, `relbar2` after the document.  By default, both blocks
-    are filled; to show the relbar only before the document, you would override
-    `relbar2` like this::
+    This block contains the *relation bar*, the list of related links (the
+    parent documents on the left, and the links to index, modules etc. on the
+    right).  `relbar1` appears before the document, `relbar2` after the
+    document.  By default, both blocks are filled; to show the relbar only
+    before the document, you would override `relbar2` like this::
 
        {% block relbar2 %}{% endblock %}
 
@@ -109,7 +118,8 @@ The following blocks exist in the ``layout`` template:
     the :data:`reldelim1`.
 
 `document`
-    The contents of the document itself.
+    The contents of the document itself.  It contains the block "body" where the
+    individual content is put by subtemplates like ``page.html``.
 
 `sidebar1` / `sidebar2`
     A possible location for a sidebar.  `sidebar1` appears before the document
@@ -166,13 +176,17 @@ using the ``{% set %}`` tag:
    defaults to ``' |'``.  Each item except of the last one in the related bar
    ends with the value of this variable.
 
-Overriding works like this:
-
-.. sourcecode:: html+jinja
+Overriding works like this::
 
    {% extends "!layout.html" %}
    {% set reldelim1 = ' >' %}
 
+.. data:: script_files
+
+   Add additional script files here, like this::
+
+      {% set script_files = script_files + [pathto("_static/myscript.js", 1)] %}
+
 
 Helper Functions
 ~~~~~~~~~~~~~~~~
@@ -200,7 +214,7 @@ them to generate links or output multiply used elements.
 
 .. function:: relbar()
 
-   Return the rendered relbar.
+   Return the rendered relation bar.
 
 
 Global Variables
@@ -210,45 +224,138 @@ These global variables are available in every template and are safe to use.
 There are more, but most of them are an implementation detail and might change
 in the future.
 
+.. data:: builder
+
+   The name of the builder (e.g. ``html`` or ``htmlhelp``).
+
+.. data:: copyright
+
+   The value of :confval:`copyright`.
+
 .. data:: docstitle
 
    The title of the documentation (the value of :confval:`html_title`).
 
-.. data:: sourcename
+.. data:: embedded
 
-   The name of the copied source file for the current document.  This is only
-   nonempty if the :confval:`html_copy_source` value is true.
+   True if the built HTML is meant to be embedded in some viewing application
+   that handles navigation, not the web browser, such as for HTML help or Qt
+   help formats.  In this case, the sidebar is not included.
 
-.. data:: builder
+.. data:: favicon
 
-   The name of the builder (e.g. ``html`` or ``htmlhelp``).
+   The path to the HTML favicon in the static path, or ``''``.
 
-.. data:: embedded
+.. data:: file_suffix
+
+   The value of the builder's :attr:`out_suffix` attribute, i.e. the file name
+   extension that the output files will get.  For a standard HTML builder, this
+   is usually ``.html``.
+
+.. data:: has_source
 
-   True if the built HTML is supposed to be embedded in some application that
-   handles navigation, e.g. HTML Help or Qt Help.
+   True if the reST document sources are copied (if :confval:`html_copy_source`
+   is true).
+
+.. data:: last_updated
+
+   The build date.
+
+.. data:: logo
+
+   The path to the HTML logo image in the static path, or ``''``.
+
+.. data:: master_doc
+
+   The value of :confval:`master_doc`, for usage with :func:`pathto`.
 
 .. data:: next
 
    The next document for the navigation.  This variable is either false or has
    two attributes `link` and `title`.  The title contains HTML markup.  For
-   example, to generate a link to the next page, you can use this snippet:
-
-   .. sourcecode:: html+jinja
+   example, to generate a link to the next page, you can use this snippet::
 
       {% if next %}
       <a href="{{ next.link|e }}">{{ next.title }}</a>
       {% endif %}
 
+.. data:: pagename
+
+   The "page name" of the current file, i.e. either the document name if the
+   file is generated from a reST source, or the equivalent hierarchical name
+   relative to the output directory (``[directory/]filename_without_extension``).
+
+.. data:: parents
+
+   A list of parent documents for navigation, structured like the :data:`next`
+   item.
+
 .. data:: prev
 
    Like :data:`next`, but for the previous page.
 
+.. data:: project
+
+   The value of :confval:`project`.
+
+.. data:: release
+
+   The value of :confval:`release`.
+
+.. data:: rellinks
+
+   A list of links to put at the left side of the relbar, next to "next" and
+   "prev".  This usually contains links to the index and the modindex.  If you
+   add something yourself, it must be a tuple ``(pagename, link title,
+   accesskey, link text)``.
+
+.. data:: shorttitle
+
+   The value of :confval:`html_short_title`.
+
+.. data:: show_source
+
+   True if :confval:`html_show_sourcelink` is true.
+
+.. data:: sphinx_version
+
+   The version of Sphinx used to build.
+
+.. data:: style
+
+   The name of the main stylesheet, as given by the theme or
+   :confval:`html_style`.
 
+.. data:: title
+
+   The title of the current document, as used in the ``<title>`` tag.
+
+.. data:: use_opensearch
+
+   The value of :confval:`html_use_opensearch`.
+
+.. data:: version
+
+   The value of :confval:`version`.
+
+
+In addition to these values, there are also all **theme options** available
+(prefixed by ``theme_``), as well as the values given by the user in
+:confval:`html_context`.
+   
 In documents that are created from source files (as opposed to
 automatically-generated files like the module index, or documents that already
 are in HTML form), these variables are also available:
 
+.. data:: meta
+
+   Document metadata, see :ref:`metadata`.
+
+.. data:: sourcename
+
+   The name of the copied source file for the current document.  This is only
+   nonempty if the :confval:`html_copy_source` value is true.
+
 .. data:: toc
 
    The local table of contents for the current page, rendered as HTML bullet
@@ -256,5 +363,5 @@ are in HTML form), these variables are also available:
 
 .. data:: toctree
 
-   The global TOC tree containing the current page, rendered as HTML bullet
-   lists.
+   A callable yielding the global TOC tree containing the current page, rendered
+   as HTML bullet lists.
diff --git a/doc/theming.rst b/doc/theming.rst
index 9f7786fb..bc150f4c 100644
--- a/doc/theming.rst
+++ b/doc/theming.rst
@@ -121,8 +121,9 @@ Python :mod:`ConfigParser` module) and has the following structure::
     variable = default value
 
 * The **inherit** setting gives the name of a "base theme", or ``none``.  The
-  base theme will be used to locate missing templates, its options will be
-  inherited, and all of its static files will be used as well.
+  base theme will be used to locate missing templates (most themes will not have
+  to supply most templates if they use ``basic`` as the base theme), its options
+  will be inherited, and all of its static files will be used as well.
 
 * The **stylesheet** setting gives the name of a CSS file which will be
   referenced in the HTML header.  If you need more than one CSS file, either
@@ -139,8 +140,25 @@ Python :mod:`ConfigParser` module) and has the following structure::
   and are accessible from all templates as ``theme_<name>``.
 
 
+Templating
+~~~~~~~~~~
+
+The :doc:`guide to templating <templating>` is helpful if you want to write your
+own templates.  What is important to keep in mind is the order in which Sphinx
+searches for templates:
+
+* First, in the user's ``templates_path`` directories.
+* Then, in the selected theme.
+* Then, in its base theme, its base's base theme, etc.
+
+From all of these levels, you can inherit templates from the lowernext level by
+prefixing the template name with an exclamation mark in the ``extends`` tag, or
+(in the case of theme templates) giving an explicit path, like
+``basic/layout.html``.
+
+
 Static templates
-----------------
+~~~~~~~~~~~~~~~~
 
 Since theme options are meant for the user to configure a theme more easily,
 without having to write a custom stylesheet, it is necessary to be able to