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.

Using the Doxphinx `header` and `footer` areas¶

The superheader, subheader, superfooter and subfooter areas provided by doxphinx can be used by adding the necessary content in a block in the layout.html file.

{% block subheader %}
    <!-- Your customized HTML code goes here -->
{% endblock %}

There is no need to include the super() directive, because these areas are empty in the default theme. They are provided to be replaced when needed.

Tip

You can use these areas to insert your advertings scripts (e.g. Google Adsense ads) in a Sphinx project.

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 word documentation.

So, 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 %}