IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

doc: Rework "templating" documents

Browse Source 
Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane 2018-10-05 09:50:33 +01:00
parent 9988d5ce26
commit e4e5c509b6
1 changed files with 45 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
doc/templating.rst
View File

@ -2,6 +2,7 @@
.. _templating: .. _templating:
==========
Templating Templating
========== ==========
@ -69,9 +70,10 @@ following contents::
By prefixing the name of the overridden template with an exclamation mark, By prefixing the name of the overridden template with an exclamation mark,
Sphinx will load the layout template from the underlying HTML theme. Sphinx will load the layout template from the underlying HTML theme.
**Important**: If you override a block, call ``{{ super() }}`` somewhere to .. important::
render the block's original content in the extended template -- unless you If you override a block, call ``{{ super() }}`` somewhere to render the
don't want that content to show up. block's original content in the extended template -- unless you don't want
that content to show up.
Working with the builtin templates Working with the builtin templates
@ -85,72 +87,68 @@ Blocks
The following blocks exist in the ``layout.html`` template: The following blocks exist in the ``layout.html`` template:
`doctype` ``doctype``
The doctype of the output format. By default this is XHTML 1.0 Transitional The doctype of the output format. By default this is XHTML 1.0 Transitional
as this is the closest to what Sphinx and Docutils generate and it's a good as this is the closest to what Sphinx and Docutils generate and it's a good
idea not to change it unless you want to switch to HTML 5 or a different but idea not to change it unless you want to switch to HTML 5 or a different but
compatible XHTML doctype. compatible XHTML doctype.
`linktags` ``linktags``
This block adds a couple of ``<link>`` tags to the head section of the This block adds a couple of ``<link>`` tags to the head section of the
template. template.
`extrahead` ``extrahead``
This block is empty by default and can be used to add extra contents into This block is empty by default and can be used to add extra contents into
the ``<head>`` tag of the generated HTML file. This is the right place to the ``<head>`` tag of the generated HTML file. This is the right place to
add references to JavaScript or extra CSS files. add references to JavaScript or extra CSS files.
`relbar1` / `relbar2` ``relbar1``, ``relbar2``
This block contains the *relation bar*, the list of related links (the 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 parent documents on the left, and the links to index, modules etc. on the
right). `relbar1` appears before the document, `relbar2` after the right). ``relbar1`` appears before the document, ``relbar2`` after the
document. By default, both blocks are filled; to show the relbar only document. By default, both blocks are filled; to show the relbar only
before the document, you would override `relbar2` like this:: before the document, you would override `relbar2` like this::
{% block relbar2 %}{% endblock %} {% block relbar2 %}{% endblock %}
`rootrellink` / `relbaritems` ``rootrellink``, ``relbaritems``
Inside the relbar there are three sections: The `rootrellink`, the links Inside the relbar there are three sections: The ``rootrellink``, the links
from the documentation and the custom `relbaritems`. The `rootrellink` is a from the documentation and the custom ``relbaritems``. The ``rootrellink``
block that by default contains a list item pointing to the master document is a block that by default contains a list item pointing to the master
by default, the `relbaritems` is an empty block. If you override them to document by default, the ``relbaritems`` is an empty block. If you
add extra links into the bar make sure that they are list items and end with override them to add extra links into the bar make sure that they are list
the :data:`reldelim1`. items and end with the :data:`reldelim1`.
`document` ``document``
The contents of the document itself. It contains the block "body" where the The contents of the document itself. It contains the block "body" where
individual content is put by subtemplates like ``page.html``. the individual content is put by subtemplates like ``page.html``.
.. note:: .. note::
In order for the built-in JavaScript search to show a page preview on In order for the built-in JavaScript search to show a page preview on
the results page, the document or body content should be wrapped in an the results page, the document or body content should be wrapped in an
HTML element containing the ``role="main"`` attribute. For example: HTML element containing the ``role="main"`` attribute. For example::
.. sourcecode:: html+jinja
<div role="main"> <div role="main">
{% block document %}{% endblock %} {% block document %}{% endblock %}
</div> </div>
`sidebar1` / `sidebar2` ``sidebar1``, ``sidebar2``
A possible location for a sidebar. `sidebar1` appears before the document A possible location for a sidebar. ``sidebar1`` appears before the document
and is empty by default, `sidebar2` after the document and contains the 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 default sidebar. If you want to swap the sidebar location override this and
call the `sidebar` helper: call the ``sidebar`` helper::
.. sourcecode:: html+jinja
{% block sidebar1 %}{{ sidebar() }}{% endblock %} {% block sidebar1 %}{{ sidebar() }}{% endblock %}
{% block sidebar2 %}{% endblock %} {% block sidebar2 %}{% endblock %}
(The `sidebar2` location for the sidebar is needed by the ``sphinxdoc.css`` (The ``sidebar2`` location for the sidebar is needed by the ``sphinxdoc.css``
stylesheet, for example.) stylesheet, for example.)
`sidebarlogo` ``sidebarlogo``
The logo location within the sidebar. Override this if you want to place The logo location within the sidebar. Override this if you want to place
some content at the top of the sidebar. some content at the top of the sidebar.
`footer` ``footer``
The block for the footer div. If you want a custom footer or markup before The block for the footer div. If you want a custom footer or markup before
or after it, override this one. or after it, override this one.
@ -159,23 +157,23 @@ list of custom sidebars in the :confval:`html_sidebars` config value. Their use
is deprecated in favor of separate sidebar templates, which can be included via is deprecated in favor of separate sidebar templates, which can be included via
:confval:`html_sidebars`. :confval:`html_sidebars`.
`sidebartoc` ``sidebartoc``
The table of contents within the sidebar. The table of contents within the sidebar.
.. deprecated:: 1.0 .. deprecated:: 1.0
`sidebarrel` ``sidebarrel``
The relation links (previous, next document) within the sidebar. The relation links (previous, next document) within the sidebar.
.. deprecated:: 1.0 .. deprecated:: 1.0
`sidebarsourcelink` ``sidebarsourcelink``
The "Show source" link within the sidebar (normally only shown if this is The "Show source" link within the sidebar (normally only shown if this is
enabled by :confval:`html_show_sourcelink`). enabled by :confval:`html_show_sourcelink`).
.. deprecated:: 1.0 .. deprecated:: 1.0
`sidebarsearch` ``sidebarsearch``
The search box within the sidebar. Override this if you want to place some The search box within the sidebar. Override this if you want to place some
content at the bottom of the sidebar. content at the bottom of the sidebar.
@ -392,7 +390,6 @@ are in HTML form), these variables are also available:
<a href="{{ next.link|e }}">{{ next.title }}</a> <a href="{{ next.link|e }}">{{ next.title }}</a>
{% endif %} {% endif %}
.. data:: page_source_suffix .. data:: page_source_suffix
The suffix of the file that was rendered. Since we support a list of The suffix of the file that was rendered. Since we support a list of
@ -424,14 +421,19 @@ are in HTML form), these variables are also available:
A callable yielding the global TOC tree containing the current page, rendered A callable yielding the global TOC tree containing the current page, rendered
as HTML bullet lists. Optional keyword arguments: as HTML bullet lists. Optional keyword arguments:
* ``collapse`` (``True`` by default): if true, all TOC entries that are not ``collapse``
ancestors of the current page are collapsed If true, all TOC entries that are not ancestors of the current page are
collapsed.
``True`` by default.
* ``maxdepth`` (defaults to the max depth selected in the toctree directive): ``maxdepth``
the maximum depth of the tree; set it to ``-1`` to allow unlimited depth The maximum depth of the tree. Set it to ``-1`` to allow unlimited depth.
Defaults to the max depth selected in the toctree directive.
* ``titles_only`` (``False`` by default): if true, put only toplevel document ``titles_only``
titles in the tree If true, put only top-level document titles in the tree.
``False`` by default.
* ``includehidden`` (``False`` by default): if true, the TOC tree will also ``includehidden``
contain hidden entries. If true, the ToC tree will also contain hidden entries.
``False`` by default.