python-sphinx - 自定义 globaltoc & localtoc html 渲染

Question

我正在使用Sphinx设置文档。我准确地说我对这个库真的很陌生。

我的文档可以使用默认主题之一构建。一切正常:)

现在，我想自定义主题。我已经更新了layout.html跟随我的皮肤。在这个模板中，我包含了globaltoc.html& localtoc.html。toctree()目录是用&渲染的toc。

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

谢谢！

score 6 · Accepted Answer

我将冒险出去猜测你在寻找什么 - 因为我认为我有同样的问题。

例如，在 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 %}

1 回答 1