修改 Sphinx TOC 树答案

【问题标题】：Modify Sphinx TOC tree修改 Sphinx TOC 树
【发布时间】：2015-11-10 18:48:44
【问题描述】：

我有一个包含:maxdepth: 2 的 TOC (index.rst) 的 Sphinx 项目。问题是我想将release 部分的深度减少到1，以便它不包括主目录中的发行说明列表（列表太长）。

似乎可以使用doctree-resolved事件处理程序修改TOC列表，但我不知道如何在事件处理程序中修改TOC树：

from sphinx import addnodes

def setup(app):
    def update_toctree(app, doctree, docname):
        if docname != 'index':
            return

        node = doctree.traverse(addnodes.toctree)[0]
        toc = app.env.resolve_toctree(docname, app.builder, node)

        # do something with "toc" here

    app.connect('doctree-resolved', update_toctree)

【问题讨论】：

遇到与您相同的问题 - 我能够读取和修改 TOC 节点，但似乎无法持久化更改。

标签： python python-sphinx

【解决方案1】：

也许不是一个理想的解决方案，但在同一页面上使用多个 toctree 条目之前，我已经做过类似的事情，例如：

####################
Presto Documentation
####################

.. toctree::
    :maxdepth: 2

    overview
    installation

.. toctree::
    :maxdepth: 1

    release

这并不理想，因为大多数主题会在树之间添加额外的填充，但在我的情况下，这比为某些页面拥有大量嵌套项要好。

【讨论】：

这是一个有趣的解决方案，但在我的情况下它没有帮助，因为我们使用“编号”，所以启动一个新的 TOC 会重置编号。

【解决方案2】：

我找到了一个技术含量低的解决方案：使用 CSS 隐藏最后一项的子项。

div.toctree-wrapper > ul > li:last-child > ul {
  display: none;
}

【讨论】：