HTML theme customization

Customizing the HTML theme

Besides configuring specific options from the default Doxphinx theme using the theme variables available in the conf.py file, it is possible to further customize the theme itself.

Overriding the theme layout

In order to customize the areas available in the theme, create a folder named _templates under the source directory. In this directory create a file named layout.html and add the following line:

{% extends "!layout.html" %}

This is a Jinja templating directive that instructs the Sphinx engine to extend the base layout.html template with the content of this file.

Customizing the layout blocks

Extending the extrahead Sphinx block

Sphinx provides a Jinja block named extrahead devoted to add additonal HTML content in the <HEAD> section of any HTML generated page. In order to enhance this block add the following Jinja2 code in the layout.html file:

{% block extrahead %}
  {{ super() }}

  <!-- Your customized scripts go here -->
  <script>
     ...
  </script>
{% endblock %}

The first line tells Sphinx to replace the extrahead block with this one. The second line with the super() directive tells, however, to include the content of the original block so it is not lost.

Tip

This is the right place to insert your analytics code (like Google Analytics) in your Sphinx documentation.

Customizing the navigation bar

Doxphinx provides a way to customize the first element in the navigation bar of the documentation. By default, Sphinx builds this element by concatenation of the variables project and release plus the word documentation. Doxphinx overrides this behavior to remove the literal word documentation.

For example, to revert back the navigation bar to include the documentation word for the first item you can use this code:

{%- block rootrellink %}
    <li class="nav-item nav-item-0">
        <a href="{{ pathto(master_doc) }}">
            {{ project }} {{ release }} documentation
        </a>
        {{ reldelim1 }}
    </li>
{%- endblock %}