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

Question

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

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

现在，我想自定义主题。我更新了 layout.html 以适应我的皮肤。在此模板中，我包含了 globaltoc.html 和 localtoc.html。 toc 使用 toctree() 和 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 编写器之间的差异，它不是 Sphinx 的直接替代品。

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

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