Skip to content

Commit 2ec1386

Browse files
jaapiojaapio
authored
Merge pull request #1219 from phpDocumentor/task/reversetoctree
[FEATURE] Support :reversed: option for toctrees
2 parents bbf30b7 + d4bdb86 commit 2ec1386

File tree

21 files changed

+382
-0
lines changed

21 files changed

+382
-0
lines changed

‎packages/guides-restructured-text/src/RestructuredText/Directives/ToctreeDirective.php

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,43 @@
3232
* which could be resolved by using https://github.com/phpDocumentor/guides/pull/21?
3333
*
3434
* @link https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents
35+
*
36+
* Parameters:
37+
*
38+
* :caption:
39+
* (Text with inline markup)
40+
* Caption to be displayed above the menu
41+
*
42+
* :depth:
43+
* (integer)
44+
* Maximum depth of the menu to display. Does not affect other menus.
45+
*
46+
* :glob:
47+
* (bool)
48+
* If true glob patterns containing stars are considered during menu building.
49+
* The entries are added to the Document Tree. Orphans are ignored
50+
*
51+
* :globExclude:
52+
* (comma separated string list)
53+
* paths to be excluded from the glob patterns
54+
*
55+
* :hidden:
56+
* (bool)
57+
* The menu will not be displayed within the content and is only used to
58+
* change the global document tree.
59+
*
60+
* :reversed:
61+
* (bool)
62+
* Display documents in reversed order. They are also added to the document
63+
* tree in reversed order and will be displayed in that order where ever a menu
64+
* is displayed
65+
*
66+
* :titlesonly:
67+
* Do not display the headlines of the current or sub documents, only display
68+
* page titles.
69+
*
70+
* :maxdepth:
71+
* Synonym of :depth:, depth prevails if both are set.
3572
*/
3673
final class ToctreeDirective extends BaseDirective
3774
{
@@ -76,6 +113,10 @@ public function process(
76113
$tocNode = $tocNode->withCaption($inlineNode);
77114
}
78115

116+
if ($directive->getOptionBool('reversed')) {
117+
$tocNode = $tocNode->withReversed(true);
118+
}
119+
79120
return $tocNode;
80121
}
81122
}

‎packages/guides/src/Compiler/NodeTransformers/MenuNodeTransformers/ToctreeSortingTransformer.php

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
/**
6+
* This file is part of phpDocumentor.
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*
11+
* @link https://phpdoc.org
12+
*/
13+
14+
namespace phpDocumentor\Guides\Compiler\NodeTransformers\MenuNodeTransformers;
15+
16+
use phpDocumentor\Guides\Compiler\CompilerContext;
17+
use phpDocumentor\Guides\Compiler\NodeTransformer;
18+
use phpDocumentor\Guides\Nodes\Menu\TocNode;
19+
use phpDocumentor\Guides\Nodes\Node;
20+
21+
use function array_reverse;
22+
use function is_array;
23+
24+
/** @implements NodeTransformer<TocNode> */
25+
final class ToctreeSortingTransformer implements NodeTransformer
26+
{
27+
public function getPriority(): int
28+
{
29+
return 3200;
30+
}
31+
32+
public function enterNode(Node $node, CompilerContext $compilerContext): Node
33+
{
34+
if (!$node instanceof TocNode) {
35+
return $node;
36+
}
37+
38+
if (!$node->isReversed()) {
39+
return $node;
40+
}
41+
42+
$entries = $node->getValue();
43+
$documentEntry = $compilerContext->getDocumentNode()->getDocumentEntry();
44+
$documentMenuEntries = $documentEntry->getMenuEntries();
45+
if (is_array($entries)) {
46+
$entries = array_reverse($entries);
47+
$documentMenuEntries = array_reverse($documentMenuEntries);
48+
}
49+
50+
$documentEntry->setMenuEntries($documentMenuEntries);
51+
$node->setValue($entries);
52+
53+
return $node;
54+
}
55+
56+
public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
57+
{
58+
return $node;
59+
}
60+
61+
public function supports(Node $node): bool
62+
{
63+
return $node instanceof TocNode;
64+
}
65+
}

‎packages/guides/src/Nodes/DocumentTree/DocumentEntryNode.php

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,12 @@ public function getMenuEntries(): array
6666
return $this->entries;
6767
}
6868

69+
/** @param array<DocumentEntryNode|ExternalEntryNode> $entries */
70+
public function setMenuEntries(array $entries): void
71+
{
72+
$this->entries = $entries;
73+
}
74+
6975
/** @return SectionEntryNode[] */
7076
public function getSections(): array
7177
{

‎packages/guides/src/Nodes/Menu/MenuNode.php

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
abstract class MenuNode extends CompoundNode
2727
{
2828
private InlineCompoundNode|null $caption = null;
29+
private bool $reversed = false;
2930
protected const DEFAULT_DEPTH = PHP_INT_MAX;
3031

3132
/** @param MenuEntryNode[] $menuEntries */
@@ -56,4 +57,17 @@ public function withCaption(InlineCompoundNode|null $caption): static
5657

5758
return $that;
5859
}
60+
61+
public function isReversed(): bool
62+
{
63+
return $this->reversed;
64+
}
65+
66+
public function withReversed(bool $reversed): MenuNode
67+
{
68+
$that = clone $this;
69+
$that->reversed = $reversed;
70+
71+
return $that;
72+
}
5973
}

‎tests/Integration/tests/toctree/toctree-glob-reverse/expected/index.html

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<!-- content start -->
2+
<div class="section" id="document-title">
3+
<h1>Document Title</h1>
4+
5+
<p>Lorem Ipsum Dolor.</p>
6+
7+
<div class="toc">
8+
<ul class="menu-level">
9+
<li class="toc-item">
10+
<a href="/page2.html#page-2">Page 2</a>
11+
12+
13+
</li>
14+
<li class="toc-item">
15+
<a href="/page1.html#page-1">Page 1</a>
16+
17+
18+
</li>
19+
</ul>
20+
</div>
21+
</div>
22+
<!-- content end -->

‎tests/Integration/tests/toctree/toctree-glob-reverse/input/doNotInclude.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:orphan:
2+
3+
Do not Include in menu
4+
======================
5+
6+
This is an orphan an must be ignored by glob patterns

‎tests/Integration/tests/toctree/toctree-glob-reverse/input/index.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
==============
2+
Document Title
3+
==============
4+
5+
Lorem Ipsum Dolor.
6+
7+
.. toctree::
8+
:glob:
9+
:titlesonly:
10+
:reversed:
11+
12+
*

‎tests/Integration/tests/toctree/toctree-glob-reverse/input/page1.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
======
2+
Page 1
3+
======
4+
5+
Lorem Ipsum Dolor.
6+
7+
Page 1 Level 2
8+
--------------
9+
10+
Page 1 Level 3
11+
~~~~~~~~~~~~~~
12+
13+
Page 1 Level 4
14+
""""""""""""""

‎tests/Integration/tests/toctree/toctree-glob-reverse/input/page2.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
======
2+
Page 2
3+
======
4+
5+
Lorem Ipsum Dolor.
6+
7+
Page 2 Level 2
8+
--------------
9+
10+
Page 2 Level 3
11+
~~~~~~~~~~~~~~
12+
13+
Page 2 Level 4
14+
""""""""""""""

‎tests/Integration/tests/toctree/toctree-level-2-reversed/expected/index.html

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
<!-- content start -->
2+
<div class="section" id="document-title">
3+
<h1>Document Title</h1>
4+
5+
<p>Lorem Ipsum Dolor.</p>
6+
7+
<div class="toc">
8+
<ul class="menu-level">
9+
<li class="toc-item">
10+
<a href="/subfolder2/index.html#subfolder-2-menu-not-reversed">Subfolder 2 Menu not reversed</a>
11+
<ul class="menu-level-1">
12+
<li class="toc-item">
13+
<a href="/subfolder2/subpage1.html#subpage-1">Subpage 1</a>
14+
15+
16+
</li>
17+
<li class="toc-item">
18+
<a href="/subfolder2/subpage2.html#subpage-2">Subpage 2</a>
19+
20+
21+
</li>
22+
</ul>
23+
24+
</li>
25+
<li class="toc-item">
26+
<a href="/subfolder/index.html#subfolder-with-reversed-menu">Subfolder with reversed menu</a>
27+
<ul class="menu-level-1">
28+
<li class="toc-item">
29+
<a href="/subfolder/subpage2.html#subpage-2">Subpage 2</a>
30+
31+
32+
</li>
33+
<li class="toc-item">
34+
<a href="/subfolder/subpage1.html#subpage-1">Subpage 1</a>
35+
36+
37+
</li>
38+
</ul>
39+
40+
</li>
41+
<li class="toc-item">
42+
<a href="/page2.html#page-2">Page 2</a>
43+
44+
45+
</li>
46+
<li class="toc-item">
47+
<a href="/page1.html#page-1">Page 1</a>
48+
49+
50+
</li>
51+
</ul>
52+
</div>
53+
</div>
54+
<!-- content end -->

‎tests/Integration/tests/toctree/toctree-level-2-reversed/expected/subfolder/index.html

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<!-- content start -->
2+
<div class="section" id="subfolder-with-reversed-menu">
3+
<h1>Subfolder with reversed menu</h1>
4+
5+
<p>Lorem Ipsum Dolor.</p>
6+
7+
<dl>
8+
<dt>A Definition List</dt>
9+
10+
<dd>Some definition.</dd>
11+
</dl>
12+
<div class="toc">
13+
<ul class="menu-level">
14+
<li class="toc-item">
15+
<a href="/subfolder/subpage2.html#subpage-2">Subpage 2</a>
16+
17+
18+
</li>
19+
<li class="toc-item">
20+
<a href="/subfolder/subpage1.html#subpage-1">Subpage 1</a>
21+
22+
23+
</li>
24+
</ul>
25+
</div>
26+
</div>
27+
<!-- content end -->

‎tests/Integration/tests/toctree/toctree-level-2-reversed/expected/subfolder2/index.html

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<!-- content start -->
2+
<div class="section" id="subfolder-2-menu-not-reversed">
3+
<h1>Subfolder 2 Menu not reversed</h1>
4+
<div class="toc">
5+
<ul class="menu-level">
6+
<li class="toc-item">
7+
<a href="/subfolder2/subpage1.html#subpage-1">Subpage 1</a>
8+
9+
10+
</li>
11+
<li class="toc-item">
12+
<a href="/subfolder2/subpage2.html#subpage-2">Subpage 2</a>
13+
14+
15+
</li>
16+
</ul>
17+
</div>
18+
</div>
19+
<!-- content end -->

‎tests/Integration/tests/toctree/toctree-level-2-reversed/input/index.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
==============
2+
Document Title
3+
==============
4+
5+
Lorem Ipsum Dolor.
6+
7+
8+
.. toctree::
9+
:glob:
10+
:titlesonly:
11+
:reversed:
12+
13+
page1
14+
page2
15+
subfolder/index
16+
subfolder2/index

‎tests/Integration/tests/toctree/toctree-level-2-reversed/input/page1.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
======
2+
Page 1
3+
======
4+
5+
Lorem Ipsum Dolor.
6+
7+
Page 1 Level 2
8+
--------------
9+
10+
Page 1 Level 3
11+
~~~~~~~~~~~~~~
12+
13+
Page 1 Level 4
14+
""""""""""""""

‎tests/Integration/tests/toctree/toctree-level-2-reversed/input/page2.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
======
2+
Page 2
3+
======
4+
5+
Lorem Ipsum Dolor.
6+
7+
Page 2 Level 2
8+
--------------
9+
10+
Page 2 Level 3
11+
~~~~~~~~~~~~~~
12+
13+
Page 2 Level 4
14+
""""""""""""""

‎tests/Integration/tests/toctree/toctree-level-2-reversed/input/subfolder/index.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
============================
2+
Subfolder with reversed menu
3+
============================
4+
5+
Lorem Ipsum Dolor.
6+
7+
A Definition List
8+
Some definition.
9+
10+
.. toctree::
11+
:glob:
12+
:titlesonly:
13+
:reversed:
14+
15+
*

0 commit comments

Comments
 (0)