如何反转“glob”标志选项提供的目录树的顺序？答案

【问题标题】：How can I reverse order the toctree provided by the "glob" flag option?如何反转“glob”标志选项提供的目录树的顺序？
【发布时间】：2011-11-30 11:10:21
【问题描述】：

有谁知道按文件名降序排列 toctree 的任何选项？如果是升序，我们可以像这样使用:glob: 选项：

.. toctree:
   :glob:

   2011*

这对于用重组文本编写的日常笔记非常方便，应该在 Sphinx 文档中报告。

【问题讨论】：

标签： sorting python-sphinx glob toctree

【解决方案1】：

没有简单的选项可以对目录树进行反向排序。但是您可以通过在将其写入文件之前修改文档结构来做到这一点。这是一个建议。将以下代码添加到 conf.py：

def reverse_toctree(app, doctree, docname):
    """Reverse the order of entries in the root toctree if 'glob' is used."""
    if docname == "index":
        for node in doctree.traverse():
            if node.tagname == "toctree" and node.get("glob"):
                node["entries"].reverse()
                break

def setup(app):
    app.connect("doctree-resolved", reverse_toctree)

reverse_toctree() 回调函数在doctree-resolved 事件被触发时被调用。该函数在文档树中定位toctree 节点并就地更改它。

有关 Sphinx 和 Docutils API 的更多详细信息：

【讨论】：

不错。这不会颠倒每个toctree吗？您可能可以在 toctree 节点中添加对 `:reversed: 参数的检查以控制此行为，不是吗？
@Kevin Horn：如果使用 :glob: 选项，代码会反转“索引”（根）文档中的目录树。 OP 没有指定任何详细要求，我并不打算将这个答案仅仅作为一个谦虚的建议。我相信有很多方法可以调整它。感谢您的评论和支持！
但这并没有反转侧边栏中的 ToC。

【解决方案2】：

这会为 toctree 添加一个反向选项。

from sphinx.directives import TocTree
from docutils.parsers.rst import directives

class NewTocTree(TocTree):
    option_spec = dict(TocTree.option_spec,
                       reversed=directives.flag)

    def run(self):
        rst = super(NewTocTree, self).run()
        if 'reversed' in self.options:
            rst[0][0]['entries'].reverse()
        return rst

def setup(app):
    app.add_directive('toctree', NewTocTree)

你可以这样做：

Contents:

.. toctree::
   :maxdepth: 2
   :reversed:
   :glob:

   20*

【讨论】：

【解决方案3】：

从 Sphinx 1.5+ 开始，您可以将一个内置的 :reversed: 标志添加到目录树中：

.. toctree::
   :glob:
   :reversed:

   2011*

有关详细信息，请参阅the Sphinx documentation。

【讨论】：

Sphinx 1.5 (1.5a2) 中添加了该功能：sphinx-doc.org/en/stable/changes.html#id30。