Merge branch '2527_reversed_toctree'

CHANGES

@@ -17,6 +17,7 @@ Features added
 * #3020: new ``'geometry'`` key to ``latex_elements`` whose default uses
   LaTeX style file ``geometry.sty`` to set page layout
 * #2843: Add :start-at: and :end-at: options to literalinclude directive
+* #2527: Add ``:reversed:`` option to toctree directive
 
 Bugs fixed
 ----------

doc/markup/toctree.rst

@@ -123,6 +123,16 @@ tables of contents.  The ``toctree`` directive is the central element.
    toctree directive.  This is useful if you want to generate a "sitemap" from
    the toctree.
 
+   You can use the ``reversed`` flag option to reverse the order of the entries
+   in the list. This can be useful when using the ``glob`` flag option to
+   reverse the ordering of the files.  Example::
+
+      .. toctree::
+         :glob:
+         :reversed:
+
+         recipe/*
+
    You can also give a "hidden" option to the directive, like this::
 
       .. toctree::

sphinx/directives/other.py

@@ -46,6 +46,7 @@ class TocTree(Directive):
         'includehidden': directives.flag,
         'numbered': int_or_nothing,
         'titlesonly': directives.flag,
+        'reversed': directives.flag,
     }
 
     def run(self):
@@ -109,6 +110,8 @@ class TocTree(Directive):
         subnode = addnodes.toctree()
         subnode['parent'] = env.docname
         # entries contains all entries (self references, external links etc.)
+        if 'reversed' in self.options:
+            entries.reverse()
         subnode['entries'] = entries
         # includefiles only entries that are documents
         subnode['includefiles'] = includefiles

tests/roots/test-toctree-glob/index.rst

@@ -1,6 +1,9 @@
 test-toctree-glob
 =================
 
+normal order
+------------
+
 .. toctree::
    :glob:
 
@@ -9,3 +12,16 @@ test-toctree-glob
    bar/*
    baz
    qux/index
+
+reversed order
+-------------
+
+.. toctree::
+   :glob:
+   :reversed:
+
+   foo
+   bar/index
+   bar/*
+   baz
+   qux/index

tests/test_environment_toctree.py

@@ -108,20 +108,35 @@ def test_glob(app, status, warning):
     toctree = app.env.tocs['index']
     assert_node(toctree,
                 [bullet_list, list_item, (compact_paragraph,  # [0][0]
-                                          [bullet_list, addnodes.toctree])])  # [0][1][0]
+                                          [bullet_list, (list_item,  # [0][1][0]
+                                                         list_item)])])  # [0][1][1]
 
     assert_node(toctree[0][0],
                 [compact_paragraph, reference, "test-toctree-glob"])
-    assert_node(toctree[0][1][0], addnodes.toctree, caption=None,
+    assert_node(toctree[0][1][0],
+                [list_item, ([compact_paragraph, reference, "normal order"],
+                             [bullet_list, addnodes.toctree])])  # [0][1][0][1][0]
+    assert_node(toctree[0][1][0][1][0], addnodes.toctree, caption=None,
                 glob=True, hidden=False, titlesonly=False,
                 maxdepth=-1, numbered=0, includefiles=includefiles,
                 entries=[(None, 'foo'), (None, 'bar/index'), (None, 'bar/bar_1'),
                          (None, 'bar/bar_2'), (None, 'bar/bar_3'), (None, 'baz'),
                          (None, 'qux/index')])
+    assert_node(toctree[0][1][1],
+                [list_item, ([compact_paragraph, reference, "reversed order"],
+                             [bullet_list, addnodes.toctree])])  # [0][1][1][1][0]
+    assert_node(toctree[0][1][1][1][0], addnodes.toctree, caption=None,
+                glob=True, hidden=False, titlesonly=False,
+                maxdepth=-1, numbered=0, includefiles=includefiles,
+                entries=[(None, 'qux/index'), (None, 'baz'), (None, 'bar/bar_3'),
+                         (None, 'bar/bar_2'), (None, 'bar/bar_1'), (None, 'bar/index'),
+                         (None, 'foo')])
+    includefiles = ['foo', 'bar/index', 'bar/bar_1', 'bar/bar_2',
+                    'bar/bar_3', 'baz', 'qux/index']
 
     # other collections
-    assert app.env.toc_num_entries['index'] == 1
-    assert app.env.toctree_includes['index'] == includefiles
+    assert app.env.toc_num_entries['index'] == 3
+    assert app.env.toctree_includes['index'] == includefiles + includefiles
     for file in includefiles:
         assert 'index' in app.env.files_to_rebuild[file]
     assert 'index' in app.env.glob_toctrees