在Sphinx文档中,如何恢复"glob"标志选项提供的toctree的顺序？

Question

有没有人知道按文件名的降序订购toctree的任何选项？在升序的情况下,我们可以使用:glob:选项,如下所示:

.. toctree:
   :glob:

   2011*

对于应在Sphinx文档中报告的重组文本中的日常注释,这将非常方便.

Answer 1

这为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*

Answer 2

没有简单的选项可以对toctree进行反向排序.但是您可以通过在将文档结构写入文件之前修改它来完成此操作.这是一个建议.将以下代码添加到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的更多详细信息:

• http://sphinx.pocoo.org/ext/appapi.html
• http://docutils.sourceforge.net/docs/ref/doctree.html

Answer 3

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

.. toctree::
   :glob:
   :reversed:

   2011*

有关详细信息，请参阅Sphinx 文档。