覆盖特定sphinx文档的html页面模板

Question

我正在使用Sphinx(https://github.com/fridge-project/dbal-docs)实现文档,并希望覆盖特定文档的html页面.我的兴趣是覆盖所有目录索引,不仅显示简单的ul.

我已经阅读了Sphinx文档,但我没有找到有关我的问题的有趣内容...有人知道解决方法吗？

Answer 1

为了记录,这个解决方案更像是一个黑客而不是一个解决方案但是现在,我找不到更好的东西......

首先,您需要了解我的解决方法是基于主题.在您的文档中,您使用主题(默认主题或自定义主题),但无论如何,您使用主题.这个主题分为不同的部分(页面,toc,...),可以单独覆盖.此覆盖可以在不同级别完成:主题本身或项目的自定义模板目录(默认情况下_templates)(可在其中配置conf.py).

我的解决方法是覆盖dir中的page.html模板,该模板_templates代表文档中的所有页面.在此模板中,您可以访问pagename(每个文件的相对文档路径).知道这一点,您可以在此模板中进行一些条件检查,以检测这是否是您要覆盖的文件,然后覆盖它.如果它不是需要被覆盖的文件,则只需回退默认行为:

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

作为解释,它真的听起来像一个黑客......

Answer 2

人们应该能够使用一个变量来定义要从.

这样，它可能就不是“黑客”了。并且您可以完全控制生成的输出（不仅是body块）。

布局.html：

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

在您的 index.rst 中，您使用页面级元数据：

索引.rst：

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