15

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

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

4

2 回答 2

14

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

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

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

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

正如解释的那样，这听起来真的像一个黑客......

于 2013-05-03T23:02:56.763 回答
8

应该能够使用一个变量来定义要扩展的模板。

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

布局.html： 

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

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

索引.rst： 

:page_template: custom/index.html
<your normal index.rst content>
于 2018-01-15T08:36:20.213 回答