simplified layout template a bit, working on templating documentation

doc/_templates/layout.html

@@ -5,10 +5,11 @@
         <li><a href="{{ pathto('contents') }}">Documentation </a> &raquo;</li>
 {% endblock %}
 
-{% block beforerelbar %}
+{% block relbar1 %}
 <div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
 <img src="{{ pathto("_static/sphinx.png", 1) }}">
 </div>
+{{ super() }}
 {% endblock %}
 
 {# put the sidebar before the body #}

doc/templating.rst

@@ -30,16 +30,178 @@ No.  You have several other options:
 Jinja/Sphinx Templating Primer
 ------------------------------
 
-The most important concept in Jinja is :dfn:`template inheritance`, which means
-that you can overwrite only specific blocks within a template, customizing it
-while also keeping the changes at a minimum.
+The default templating language in Sphinx is Jinja.  It's Django/Smarty inspired
+and easy to understand.  The most important concept in Jinja is
+:dfn:`template inheritance`, which means that you can overwrite only specific
+blocks within a template, customizing it while also keeping the changes at a
+minimum.
 
-Inheritance is done via two (Jinja) directives, ``extends`` and ``block``.
+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.
 
-.. template path
-   blocks
-   extends !template
+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.  You can have a look at them by browsing
+the sphinx directory in your site packages folder.
 
-   template names for other template engines
+A template contains **variables**, which get replaced with values when the
+template is evaluated, **tags**, which control the logic of the template and
+**blocks** which are used for template inheritance.
 
-.. XXX continue this
+Sphinx provides base templates with a couple of blocks it will fill with data.
+The default templates are located in the `templates` folder of the sphinx
+installation directory.  Templates with the same name in the
+:confval:`templates_path` override templates from the builtin folder.
+
+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
+
+    {% extends "!layout.html" %}
+    {% block rootrellink %}
+        <li><a href="http://project.invalid/">Project Homepage</a> &raquo;</li>
+        {{ super() }}
+    {% endblock %}
+
+By prefixing the parent template with an exclamation mark, sphinx will load
+the builtin layout template.  If you override a block you should call
+``{{ super() }}`` to render the parent contents unless you don't want the
+parent contents to show up.
+
+
+Blocks
+~~~~~~
+
+The following blocks exist in the layout template:
+
+`doctype`
+    The doctype of the output format.  By default this is XHTML 1.0
+    Transitional as this is the closest to what sphinx generates and it's a
+    good idea not to change it unless you want to switch to HTML 5 or a
+    different but compatible XHTML doctype.
+
+`rellinks`
+    This block adds a couple of `<link>` tags to the head section of the
+    template.
+
+`extrahead`
+    This block is empty by default and can be used to add extra contents
+    into the head section of the generated HTML file.  This is the right
+    place to add references to javascript or extra CSS files.
+
+`relbar1` / `relbar2`
+    This block contains the list of related links.  `relbar1` appears
+    before the document, `relbar2` after.
+
+`rootrellink` / `relbaritems`
+    Inside the rel bar there are three sections.  The `rootrellink`, the links
+    from the documentation and the `relbaritems`.  The `rootrellink` is a list
+    item that points to the index of the documentation by default, the
+    `relbaritems` are empty.  If you override them to add extra links into
+    the bar make sure that they are list items and end with the `reldelim1`.
+
+`document`
+    The contents of the document itself.
+
+`sidebar1` / `sidebar2`
+    A possible location for a sidebar.  `sidebar1` appears before the document
+    and is empty by default, `sidebar2` after the document and contains the
+    default sidebar.  If you want to swap the sidebar location override
+    this and call the `sidebar` helper:
+
+    .. sourcecode:: html+jinja
+
+        {% block sidebar1 %}{{ sidebar() }}{% endblock %}
+        {% block sidebar2 %}{% endblock %}
+
+`footer`
+    The block for the footer div.  If you want a custom footer or markup before
+    or after it, override this one.
+
+
+Configuration Variables
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Inside templates you can set a couple of variables used by the layout template
+using the ``{% set %}`` tag:
+
+.. data:: reldelim1
+    The delimiter for the items on the left side of the related bar.  This
+    defaults to ``' &raquo;'``  Each item in the related bar ends with the
+    value of this variable.
+
+.. data:: reldelim2
+    The delimiter for the items on the right side of the related bar.  This
+    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
+
+    {% extends "!layout.html" %}
+    {% set reldelim1 = ' &gt;' %}
+
+
+Helper Functions
+~~~~~~~~~~~~~~~~
+
+Sphinx provides various helper functions in the template you can use to
+generate links or output often used elements.
+
+.. function:: pathto(file)
+
+    Returns the path to a file as URL.
+
+.. function:: hasdoc(target)
+
+    Checks if a document with the name `target` exists.
+
+.. function:: sidebar()
+
+    Returns the rendered sidebar.
+
+.. function:: relbar()
+
+    Returns the rendered relbar.
+
+
+Global Variables
+~~~~~~~~~~~~~~~~
+
+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:: docstitle
+
+    The title of the documentation.
+
+.. data:: sourcename
+
+    The name of the source file
+
+.. data:: builder
+
+    The name of the builder (``html``, ``htmlhelp``, or ``web``)
+
+.. data:: next
+
+    The next document for the navigation.  This variable is either falsy
+    or has two attributes `link` and `title`.  The title contiains HTML
+    markup.  For example to generate a link to the next page one can use
+    this snippet:
+
+    .. sourcecode:: html+jinja
+
+        {% if next %}
+        <a href="{{ next.link|e }}">{{ next.title }}</a>
+        {% endif %}
+
+.. data:: prev
+
+    Like `next` but for the previous page.

sphinx/templates/defindex.html

@@ -7,8 +7,6 @@
     {% block description %}the documentation for {{ project }}
     {{ release }}{% if last_updated %}, last updated {{ last_updated }}{% endif %}{% endblock %}.
   </p>
-  {% block beforetables %}
-  {% endblock %}
   {% block tables %}
   <p><strong>Indices and tables:</strong></p>
   <table class="contentstable" align="center"><tr>
@@ -25,6 +23,4 @@
     </td></tr>
   </table>
   {% endblock %}
-  {% block aftertables %}
-  {% endblock %}
 {% endblock %}

sphinx/templates/layout.html

@@ -1,8 +1,10 @@
-{%- include "macros.html" %}
 {%- block doctype -%}
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 {%- endblock %}
+{%- set reldelim1 = reldelim1 is not defined and ' &raquo;' or reldelim1 %}
+{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %}
+{%- include "macros.html" %}
 {%- macro relbar %}
 {# this macro needs to stay in layout.html due to it containing blocks #}
     <div class="related">
@@ -10,23 +12,23 @@
       <ul>
         <li class="right" style="margin-right: 10px"><a href="{{ pathto('genindex') }}" title="General Index" accesskey="I">index</a></li>
         {%- if use_modindex %}
-        <li class="right"><a href="{{ pathto('modindex') }}" title="Global Module Index" accesskey="M">modules</a> |</li>
+        <li class="right"><a href="{{ pathto('modindex') }}" title="Global Module Index" accesskey="M">modules</a>{{ reldelim2 }}</li>
         {%- endif %}
         {%- if next %}
-          <li class="right"><a href="{{ next.link|e }}" title="{{ next.title|striptags }}" accesskey="N">next</a> |</li>
+          <li class="right"><a href="{{ next.link|e }}" title="{{ next.title|striptags }}" accesskey="N">next</a>{{ reldelim2 }}</li>
         {%- endif %}
         {%- if prev %}
-          <li class="right"><a href="{{ prev.link|e }}" title="{{ prev.title|striptags }}" accesskey="P">previous</a> |</li>
+          <li class="right"><a href="{{ prev.link|e }}" title="{{ prev.title|striptags }}" accesskey="P">previous</a>{{ reldelim2 }}</li>
         {%- endif %}
         {%- if builder == 'web' %}
           <li class="right"><a href="{{ pathto('settings') }}"
                                title="Customize your viewing settings" accesskey="S">settings</a> |</li>
         {%- endif %}
         {%- block rootrellink %}
-        <li><a href="{{ pathto('index') }}">{{ docstitle }}</a> &raquo;</li>
+        <li><a href="{{ pathto('index') }}">{{ docstitle }}</a>{{ reldelim1 }}</li>
         {%- endblock %}
         {%- for parent in parents %}
-          <li><a href="{{ parent.link|e }}" accesskey="U">{{ parent.title }}</a> &raquo;</li>
+          <li><a href="{{ parent.link|e }}" accesskey="U">{{ parent.title }}</a>{{ reldelim1 }}</li>
         {%- endfor %}
         {%- block relbaritems %}{% endblock %}
       </ul>
@@ -85,15 +87,11 @@
   </head>
   <body>
 
-{%- block beforerelbar %}{% endblock %}
 {%- block relbar1 %}{{ relbar() }}{% endblock %}
-{%- block afterrelbar %}{% endblock %}
 
-{%- block beforesidebar1 %}{% endblock %}
 {%- block sidebar1 %}{# possible location for sidebar #}{% endblock %}
-{%- block aftersidebar1 %}{% endblock %}
 
-{%- block beforedocument %}{% endblock %}
+{%- block document %}
     <div class="document">
       <div class="documentwrapper">
       {%- if builder != 'htmlhelp' %}
@@ -106,17 +104,14 @@
         </div>
       {%- endif %}
       </div>
-{%- block afterdocument %}{% endblock %}
+{%- endblock %}
 
-{%- block beforesidebar2 %}{% endblock %}
 {%- block sidebar2 %}{{ sidebar() }}{% endblock %}
-{%- block aftersidebar2 %}{% endblock %}
       <div class="clearer"></div>
     </div>
 
 {%- block relbar2 %}{{ relbar() }}{% endblock %}
 
-{%- block beforefooter %}{% endblock %}
 {%- block footer %}
     <div class="footer">
     {%- if hasdoc('copyright') %}
@@ -129,6 +124,5 @@
     {%- endif %}
     </div>
 {%- endblock %}
-{%- block afterfooter %}{% endblock %}
   </body>
 </html>