From ca49c4c207fcec41602ed978803a99315eaed279 Mon Sep 17 00:00:00 2001 From: "John L. Villalovos" Date: Wed, 4 May 2016 16:11:57 -0700 Subject: [PATCH 1/4] 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 | 10 ++++++++++ sphinx/directives/other.py | 3 +++ 2 files changed, 13 insertions(+) diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst index b4c7105fd..81f99504e 100644 --- a/doc/markup/toctree.rst +++ b/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:: diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 51294570c..e518729aa 100644 --- a/sphinx/directives/other.py +++ b/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 From f22bbf668d70127b8af103a56d98b721142543b5 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Wed, 12 Oct 2016 19:32:48 +0900 Subject: [PATCH 2/4] Add testcase for reversed toctree --- tests/roots/test-toctree-glob/index.rst | 16 ++++++++++++++++ tests/test_environment_toctree.py | 23 +++++++++++++++++++---- 2 files changed, 35 insertions(+), 4 deletions(-) diff --git a/tests/roots/test-toctree-glob/index.rst b/tests/roots/test-toctree-glob/index.rst index 079cd6027..ff5ba8fe7 100644 --- a/tests/roots/test-toctree-glob/index.rst +++ b/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: + :reverse: + + foo + bar/index + bar/* + baz + qux/index diff --git a/tests/test_environment_toctree.py b/tests/test_environment_toctree.py index fe10da660..20188c16a 100644 --- a/tests/test_environment_toctree.py +++ b/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 From c8fe4a1848b8d6734d5c9bd7439dcaac385980ac Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Wed, 12 Oct 2016 19:36:49 +0900 Subject: [PATCH 3/4] Rename :reverse: option of toctree directive to :reversed: --- doc/markup/toctree.rst | 4 ++-- sphinx/directives/other.py | 4 ++-- tests/roots/test-toctree-glob/index.rst | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst index 81f99504e..a0161ee3c 100644 --- a/doc/markup/toctree.rst +++ b/doc/markup/toctree.rst @@ -123,13 +123,13 @@ 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 + 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: - :reverse: + :reversed: recipe/* diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 23671be07..1c9c5016b 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -46,7 +46,7 @@ class TocTree(Directive): 'includehidden': directives.flag, 'numbered': int_or_nothing, 'titlesonly': directives.flag, - 'reverse': directives.flag, + 'reversed': directives.flag, } def run(self): @@ -110,7 +110,7 @@ class TocTree(Directive): subnode = addnodes.toctree() subnode['parent'] = env.docname # entries contains all entries (self references, external links etc.) - if 'reverse' in self.options: + if 'reversed' in self.options: entries.reverse() subnode['entries'] = entries # includefiles only entries that are documents diff --git a/tests/roots/test-toctree-glob/index.rst b/tests/roots/test-toctree-glob/index.rst index ff5ba8fe7..a3c198ce3 100644 --- a/tests/roots/test-toctree-glob/index.rst +++ b/tests/roots/test-toctree-glob/index.rst @@ -18,7 +18,7 @@ reversed order .. toctree:: :glob: - :reverse: + :reversed: foo bar/index From d87608ea1dcabdc041295e222c135786c8f75fa9 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Wed, 12 Oct 2016 19:37:36 +0900 Subject: [PATCH 4/4] Update CHANGES for PR#2527 --- CHANGES | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES b/CHANGES index 5d0abbad3..2e1fc1d29 100644 --- a/CHANGES +++ b/CHANGES @@ -15,6 +15,7 @@ Features added * #3008: ``linkcheck`` builder ignores self-signed certificate URL * #3020: new ``'geometry'`` key to ``latex_elements`` whose default uses LaTeX style file ``geometry.sty`` to set page layout +* #2527: Add ``:reversed:`` option to toctree directive Bugs fixed ----------