Add a 'reverse' flag option to 'toctree'

I'm not sure the best way to do the unit tests. A little confused. So
help would be appreciated :)

Add the ability to reverse the list of entries when using 'toctree'.
This is likely most useful for people using the 'glob' flag option with
'toctree'

Change-Id: I1852479106c3d9c8253fd1625ced0077af0304e3

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 ``reverse`` 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:
+         :reverse:
+
+         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,
+        'reverse': 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 'reverse' in self.options:
+            entries.reverse()
         subnode['entries'] = entries
         # includefiles only entries that are documents
         subnode['includefiles'] = includefiles