Question

我正在使用Sphinx（https://github.com/fridge-project/dbal-docs）＆amp;想要覆盖特定文档的html页面。我的兴趣是覆盖所有目录索引，不仅显示简单的ul。

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

Answer 1

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

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

我的解决方法是覆盖代表文档中所有页面的page.html目录中的_templates模板。在此模板中，您可以访问pagename（每个文件的相对文档路径）。知道了，您可以在此模板中进行一些条件检查，以检测这是否是您要覆盖的文件＆amp;然后覆盖它。如果它不是需要被覆盖的文件，则只需回退默认行为：

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

作为解释，这真的听起来像是黑客......

Answer 2

应该能够使用变量来定义template to extend from。

通过这种方式，它可能不再是“黑客”。并且您可以完全控制生成的输出（不仅是body块）。

layout.html：

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

然后在index.rst中使用page-level metadata：

index.rst：

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

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

2 个答案: