Geek Answers Handbook

Override html page template for specific sphinx document

I am using documentation using Sphinx ( https://github.com/fridge-project/dbal-docs ) and would like to override the html page of a specific document. I am interested in overriding all directory indexes so as not to just show a simple street.

I read the Sphinx documentation, but did not find anything interesting in my problem ... Does anyone know a workaround?

+8
python-sphinx
source share
2 answers

For the record, this solution is much more complicated than the solution, but at the moment I do not find something better ...

First of all you need to understand, my workaround is topic-based. You use a theme in your document (the default is one or a custom one), but in any case you use a theme. This topic is divided into another part (page, toc, ...), which can be individually redefined. This redefinition can be performed at a different level: the theme itself or in the directory of custom project templates (by default _templates ) (configured in conf.py ).

My workaround is to override the page.html template in the page.html directory, which represents all the pages in your documentation. In this template, you have access to pagename (relative path to the document for each file). Knowing this, you can do some conditional checking in this template to determine if this is the file you want to override, and then override. If this is not a file to be redefined, simply undo the default behavior:

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

They explain that it really sounds like a hack ...

+10
source share

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

Thus, it can be less than “hacking”. And you have full control over the generated output (and not just with the body block).

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

And in your index.rst you use 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>

0
source share

More articles:


All Articles