Advanced¶

Though I want to create theme,

what a structure it is?

Structure of HTML theme is like this:

pyconjp
    + theme.conf
    + layout.html
        :
    + static
        + pyconjp.css_t
        + pyconjp_2012_logo.png

• theme.conf
• HTML template files
• static files
  • stylesheet(s)
  • images

theme.conf

[theme]
inherit = basic
stylesheet = pyconjp.css_t
pygments_style = friendly

[options]
rightsidebar = false

[theme] Section

• inherit
• stylesheet
• pygments_style

[theme] Section - inherit

• Specify a inherit theme.
• Specify “none” when inherit no theme.
• It is useful in case of modifying a builtin theme partly.

[theme] Section - stylesheet

• Specify a stylesheet name.
• It can use the “Static template”.
• html_style option in conf.py can overwrite this in runtime.

[theme] Section - pygments_style

• Style of code block.
• Specify a Pygments style name.
• pygments_style option in conf.py can overwrite this in runtime.

[options] Section

• Define options of theme’s own.
• “OptionName = Value”
• html_theme_options option in conf.py can overwrite this in runtime.

HTML template file

{#
    default/layout.html
    ~~~~~~~~~~~~~~~~~~~

    Sphinx layout template for the default theme.

    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.
#}
{% extends "basic/layout.html" %}

{% if theme_collapsiblesidebar|tobool %}
{% set script_files = script_files + ['static/sidebar.js'] %}
{% endif %}

HTML template file

• Template file of Jinja2 style.
• Use template of inherited theme if custom template files not exists.

Static files

• Stylesheet(s)
• Image files (e.g. *.jpg, *.png)

Stylesheet

• It can use the “Static template”.

What is the “Static template”?

• Templating of static files.
• It can embed values into static files at runtime.

pyconjp.css_t

       :
div.sphinxsidebar {
    margin: 0;
    padding: 0.5em  15px 15px 0;
    width: {{ theme_sidebarwidth|toint - 20 }}px
    float: right;
    font-size: 1em;
    text-align: left;
}
       :

Syntax:

* Embed a variable which enclosed with double curly braces.
* Specify a variable name which prefixed with "theme_".

theme.conf

[theme]
inherit = basic
stylesheet = pyconjp.css_t
pygments_style = sphinx

[options]
sidebarwidth = 170

pyconjp.css

       :
div.sphinxsidebar {
    margin: 0;
    padding: 0.5em  15px 15px 0;
    width: 150px
    float: right;
    font-size: 1em;
    text-align: left;
}
       :

* It can use not only numeric, also string.
* It can use filter as same as HTML template.

It enclose these files with one directory:

pyconjp
    + theme.conf
    + layout.html
         :
    + static
        + pyconjp.css_t
        + pyconjp_2012_logo.png

And, put it under the document root of Sphinx:

some_document
    + static
    + _templates
    + conf.py
    + index.rst
    + pyconjp     <-- New!

In conf.py, specify the html_theme_path to current directly, type “make html”, and...

# Add any paths that contain custom themes here, relative to
# this directory.
html_theme_path = ["."]

• It can be specify a relatibe path from conf.py.

You can see a custom themed document :-)

All the contents of this session are included in HTML theming support section of official document.

Please refer to document and try to modify a theme.