Override html page template for a specific sphinx document

问题:

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?

回答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...

回答2:

One should be able to use a variable to define the template to extend from. http://jinja.pocoo.org/docs/2.10/templates/#template-objects

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-meta-data: http://www.sphinx-doc.org/en/stable/markup/misc.html#file-wide-metadata

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

文章来源: Override html page template for a specific sphinx document