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

Question

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

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

Answer 1

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

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

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

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

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