Override html page template for a specific sphinx document

Question

I'm implementing a documentation using Sphinx (https://github.com/fridge-project/dbal-docs) & would like to override the html page of a specific document. My interest is to override all directory indexes to not only show a simple ul.

I have read the Sphinx documentation but I don't find something interesting about my issue... Does someone know a workaround?

Answer 1

For the record, this solution is much more a hack than a solution but for now, I don't find something better...

First, of all you need to understand my workaround is based on the theming. In your doc, you use a theme (the default one or a custom one) but anyway, you use a theme. This theme is divided in different part (page, toc, ...) which can be individually overridden. This override can be done at different level: the theme itself or in the custom template directory of the project (by default _templates) (configurable in the conf.py).

My workaround is to override the page.html template in the _templates dir which represents all pages in your documentation. In this template, you have access to the pagename (relative doc path of each file). Knowing that, you can make some conditional check in this template to detect if this is a file you want to override & then override it. If it is not a file which need to be overridden, simply fallback on the default behavior:

{% extends "layout.html" %}
{% block body %}
    {% if pagename == 'index' %}
        {% include 'custom/index.html' %}
    {% else %}
        {{ body }}
    {% endif %}
{% endblock %}

As explain, it really sounds like a hack...

Answer 2

One should be able to use a variable to define the template to extend from.

In that way it might be less of a 'hack'. And you have full control about the generated output(not only the body block).

layout.html:

{% extends meta.page_template|default('basic/page.html') %}

And in your index.rst you use then page-level metadata:

index.rst:

:page_template: custom/index.html
<your normal index.rst content>