Introduce Transformer for Content Menus

This reintroduces the contents directive which was destroyed by switching to transformers

Author: linawolf

packages/guides-restructured-text/src/RestructuredText/Directives/ContentsDirective.php

@@ -4,7 +4,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Directives;
 
-use phpDocumentor\Guides\Nodes\ContentMenuNode;
+use phpDocumentor\Guides\Nodes\Menu\ContentMenuNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;

packages/guides/src/Compiler/NodeTransformers/ContentMenuNodeWithSectionEntryTransformer.php

@@ -0,0 +1,101 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\Compiler\NodeTransformers;
+
+use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\NodeTransformer;
+use phpDocumentor\Guides\Nodes\DocumentTree\DocumentEntryNode;
+use phpDocumentor\Guides\Nodes\DocumentTree\SectionEntryNode;
+use phpDocumentor\Guides\Nodes\Menu\ContentMenuNode;
+use phpDocumentor\Guides\Nodes\Menu\MenuEntryNode;
+use phpDocumentor\Guides\Nodes\Menu\TocNode;
+use phpDocumentor\Guides\Nodes\Node;
+
+use function assert;
+
+use const PHP_INT_MAX;
+
+/** @implements NodeTransformer<TocNode> */
+class ContentMenuNodeWithSectionEntryTransformer implements NodeTransformer
+{
+    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    {
+        return $node;
+    }
+
+    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    {
+        if (!$node instanceof ContentMenuNode) {
+            return $node;
+        }
+
+        $depth = (int) $node->getOption('depth', PHP_INT_MAX);
+        $documentEntry = $compilerContext->getDocumentNode()->getDocumentEntry();
+
+        $menuEntries = [];
+        foreach ($documentEntry->getSections() as $section) {
+            // We do not add the main section as it repeats the document title
+            foreach ($section->getChildren() as $subSectionEntryNode) {
+                assert($subSectionEntryNode instanceof SectionEntryNode);
+                $sectionMenuEntry = new MenuEntryNode(
+                    $documentEntry->getFile(),
+                    $subSectionEntryNode->getTitle(),
+                    [],
+                    false,
+                    1,
+                    $subSectionEntryNode->getId(),
+                );
+                $menuEntries[] = $sectionMenuEntry;
+                $this->addSubSections($sectionMenuEntry, $subSectionEntryNode, $documentEntry, 1, $depth);
+            }
+        }
+
+        $node = $node->withMenuEntries($menuEntries);
+
+        return $node;
+    }
+
+    private function addSubSections(
+        MenuEntryNode $sectionMenuEntry,
+        SectionEntryNode $sectionEntryNode,
+        DocumentEntryNode $documentEntry,
+        int $currentLevel,
+        int $maxLevel,
+    ): void {
+        if ($currentLevel >= $maxLevel) {
+            return;
+        }
+
+        foreach ($sectionEntryNode->getChildren() as $subSectionEntryNode) {
+            $subSectionMenuEntry = new MenuEntryNode(
+                $documentEntry->getFile(),
+                $subSectionEntryNode->getTitle(),
+                [],
+                false,
+                $currentLevel,
+                $subSectionEntryNode->getId(),
+            );
+            $sectionMenuEntry->addSection($subSectionMenuEntry);
+            $this->addSubSections(
+                $subSectionMenuEntry,
+                $subSectionEntryNode,
+                $documentEntry,
+                $currentLevel + 1,
+                $maxLevel,
+            );
+        }
+    }
+
+    public function supports(Node $node): bool
+    {
+        return $node instanceof ContentMenuNode;
+    }
+
+    public function getPriority(): int
+    {
+        // After DocumentEntryTransformer
+        return 4500;
+    }
+}

packages/guides/src/Compiler/NodeTransformers/DocumentEntryRegistrationTransformer.php

@@ -38,7 +38,7 @@ public function leaveNode(Node $node, CompilerContext $compilerContext): Node|nu
         $entry = new DocumentEntryNode($node->getFilePath(), $node->getTitle() ?? TitleNode::emptyNode());
         $compilerContext->getProjectNode()->addDocumentEntry($entry);
 
-        return $node->withDocumentEntry($entry);
+        return $node->setDocumentEntry($entry);
     }
 
     public function supports(Node $node): bool

packages/guides/src/Compiler/NodeTransformers/MenuNodeTransformer.php

@@ -29,7 +29,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
 
         $sectionEntryNode = new SectionEntryNode($node->getTitle());
         if (count($this->sectionStack) === 0) {
-            $compilerContext->getDocumentNode()->getDocumentEntry()?->addSection($sectionEntryNode);
+            $compilerContext->getDocumentNode()->getDocumentEntry()->addSection($sectionEntryNode);
         } else {
             $parentSection = end($this->sectionStack);
             assert($parentSection instanceof SectionEntryNode);

packages/guides/src/Compiler/NodeTransformers/SectionEntryRegistrationTransformer.php

@@ -80,14 +80,14 @@ public function leaveNode(Node $node, CompilerContext $compilerContext): Node|nu
     private function addSubSections(MenuEntryNode $sectionMenuEntry, SectionEntryNode $sectionEntryNode, DocumentEntryNode $documentEntry, int $currentLevel): void
     {
         foreach ($sectionEntryNode->getChildren() as $subSectionEntryNode) {
-            $sectionMenuEntry = new MenuEntryNode($documentEntry->getFile(), $subSectionEntryNode->getTitle(), [], false, $currentLevel, $subSectionEntryNode->getId());
-            $sectionMenuEntry->addSection($sectionMenuEntry);
+            $subSectionMenuEntry = new MenuEntryNode($documentEntry->getFile(), $subSectionEntryNode->getTitle(), [], false, $currentLevel + 1, $subSectionEntryNode->getId());
+            $sectionMenuEntry->addSection($subSectionMenuEntry);
         }
     }
 
     public function supports(Node $node): bool
     {
-        return $node instanceof MenuNode;
+        return $node instanceof TocNode;
     }
 
     public function getPriority(): int

packages/guides/src/Compiler/NodeTransformers/TocNodeWithDocumentEntryTransformer.php

@@ -14,7 +14,7 @@
 namespace phpDocumentor\Guides\NodeRenderers\Html;
 
 use phpDocumentor\Guides\NodeRenderers\NodeRenderer;
-use phpDocumentor\Guides\Nodes\ContentMenuNode;
+use phpDocumentor\Guides\Nodes\Menu\ContentMenuNode;
 use phpDocumentor\Guides\Nodes\Menu\MenuNode;
 use phpDocumentor\Guides\Nodes\Menu\TocNode;
 use phpDocumentor\Guides\Nodes\Node;

packages/guides/src/NodeRenderers/Html/MenuNodeRenderer.php

@@ -13,6 +13,7 @@
 
 namespace phpDocumentor\Guides\Nodes;
 
+use Exception;
 use phpDocumentor\Guides\Meta\FootnoteTarget;
 use phpDocumentor\Guides\Nodes\DocumentTree\DocumentEntryNode;
 use phpDocumentor\Guides\Nodes\DocumentTree\SectionEntryNode;
@@ -245,17 +246,20 @@ public function getFootnoteTargetAnonymous(): FootnoteTarget|null
         return null;
     }
 
-    public function getDocumentEntry(): DocumentEntryNode|null
+    public function getDocumentEntry(): DocumentEntryNode
     {
+        if ($this->documentEntry === null) {
+            throw new Exception('DocumentEntry may not be accessed before initialization');
+        }
+
         return $this->documentEntry;
     }
 
-    public function withDocumentEntry(DocumentEntryNode $documentEntry): DocumentNode
+    public function setDocumentEntry(DocumentEntryNode $documentEntry): DocumentNode
     {
-        $node = clone$this;
-        $node->documentEntry = $documentEntry;
+        $this->documentEntry = $documentEntry;
 
-        return $node;
+        return $this;
     }
 
     public function getRootSectionEntry(): SectionEntryNode|null

packages/guides/src/Nodes/DocumentNode.php

@@ -11,9 +11,7 @@
  * @link https://phpdoc.org
  */
 
-namespace phpDocumentor\Guides\Nodes;
-
-use phpDocumentor\Guides\Nodes\Menu\MenuNode;
+namespace phpDocumentor\Guides\Nodes\Menu;
 
 use function is_scalar;