自定义globaltoc和localtoc html渲染

Question

我正在使用Sphinx设置文档。我精确地说，我真的是这个库的新手。

我的文档可以使用默认主题之一进行构建。一切正常：）

现在，我想自定义主题。我已经更新了layout.html以适应我的皮肤。在此模板中，我包含globaltoc.html和localtoc.html。使用toctree()和toc渲染Toc。

我想知道是否有一种方法可以更新生成的html，或者是否需要使css适应生成的html？

谢谢！

Answer 1

我将四肢不停地猜测您要寻找的东西-因为我认为我也遇到了同样的问题。

作为示例，在localtoc.html中，模板如下所示：

<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
    {{ toc }}
{%- endif %}

{{ toc }}是Sphinx的全局宏，我花了大约一个小时的时间来尝试查找它的定义位置，但绝对没有运气。

警告，{{ toc }}呈现为类似以下内容：

<ul>
   <li>Toc Item 1</li>
   <li>Toc Item 2</li>
   <li>Toc Item 3</li>
</ul>

问题是，如果您的CSS要按类处理<ul>或<li>标签，则无法轻松更改它们。最终，我认为这是Sphinx的writers / html.py的局限性，仍然需要手动完成很多工作。

真正的解决方案是替换（可能是builders / html.py），但肯定是Sphinx中的writers / html.py。这比我要花费的精力多得多。

我确实找到了一些解决了这个问题，但只是部分解决了这些问题的人：

rst2html5，其中包含html5css3 HTMLWriter和HTMLTransformer。和docutils-html5-writer，看起来非常不错-但由于builders / html.py和html5 writer之间的差异，因此不是Sphinx的直接替代。

最终，我想出了这个解决方案，使用了Jinja过滤器。这是一个丑陋的骇客，但它使我越过了障碍。

<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
   {{ toc|replace("<ul>", "<ul class=\"custom\">", 1) }}
{%- endif %}