[Python-checkins] r62522 - in doctools/trunk: doc/_templates/layout.html doc/templating.rst sphinx/templates/defindex.html sphinx/templates/layout.html
armin.ronacher
python-checkins at python.org
Sun Apr 27 16:23:12 CEST 2008
Author: armin.ronacher
Date: Sun Apr 27 16:23:11 2008
New Revision: 62522
Log:
simplified layout template a bit, working on templating documentation
Modified:
doctools/trunk/doc/_templates/layout.html
doctools/trunk/doc/templating.rst
doctools/trunk/sphinx/templates/defindex.html
doctools/trunk/sphinx/templates/layout.html
Modified: doctools/trunk/doc/_templates/layout.html
==============================================================================
--- doctools/trunk/doc/_templates/layout.html (original)
+++ doctools/trunk/doc/_templates/layout.html Sun Apr 27 16:23:11 2008
@@ -5,10 +5,11 @@
<li><a href="{{ pathto('contents') }}">Documentation </a> »</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 #}
Modified: doctools/trunk/doc/templating.rst
==============================================================================
--- doctools/trunk/doc/templating.rst (original)
+++ doctools/trunk/doc/templating.rst Sun Apr 27 16:23:11 2008
@@ -30,16 +30,178 @@
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> »</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 ``' »'`` 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 = ' >' %}
+
+
+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.
Modified: doctools/trunk/sphinx/templates/defindex.html
==============================================================================
--- doctools/trunk/sphinx/templates/defindex.html (original)
+++ doctools/trunk/sphinx/templates/defindex.html Sun Apr 27 16:23:11 2008
@@ -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 %}
Modified: doctools/trunk/sphinx/templates/layout.html
==============================================================================
--- doctools/trunk/sphinx/templates/layout.html (original)
+++ doctools/trunk/sphinx/templates/layout.html Sun Apr 27 16:23:11 2008
@@ -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 ' »' 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> »</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> »</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>
More information about the Python-checkins
mailing list