Merge pull request #804 from phpDocumentor/bugfix/menu-warning

[BUGFIX] Generate Warning when menu entry was not found

Author: jaapio

packages/guides/src/Compiler/NodeTransformers/MenuNodeTransformers/GlobMenuEntryNodeTransformer.php

@@ -88,8 +88,9 @@ public function supports(Node $node): bool
 
     public function getPriority(): int
     {
-        // After DocumentEntryTransformer
-        return 4500;
+        // After GlobMenuEntryNodeTransformer
+        // Before SubInternalMenuEntry
+        return 4000;
     }
 
     /** @param String[] $globExclude */

packages/guides/src/Compiler/NodeTransformers/MenuNodeTransformers/InternalMenuEntryNodeTransformer.php

@@ -15,6 +15,7 @@
 use function assert;
 use function explode;
 use function implode;
+use function sprintf;
 
 class InternalMenuEntryNodeTransformer extends AbstractMenuEntryNodeTransformer
 {
@@ -36,6 +37,7 @@ protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNo
         $documentEntries = $compilerContext->getProjectNode()->getAllDocumentEntries();
         $currentPath = $compilerContext->getDocumentNode()->getFilePath();
         $maxDepth = (int) $currentMenu->getOption('maxdepth', self::DEFAULT_MAX_LEVELS);
+
         foreach ($documentEntries as $documentEntry) {
             if (
                 !self::matches($documentEntry->getFile(), $entryNode, $currentPath)
@@ -65,7 +67,9 @@ protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNo
             return [$newEntryNode];
         }
 
-        return [$entryNode];
+        $this->logger->warning(sprintf('Menu entry "%s" was not found in the document tree. Ignoring it. ', $entryNode->getUrl()), $compilerContext->getLoggerInformation());
+
+        return [];
     }
 
     private static function matches(string $actualFile, InternalMenuEntryNode $parsedMenuEntryNode, string $currentFile): bool

packages/guides/src/Compiler/NodeTransformers/MenuNodeTransformers/SubInternalMenuEntryNodeTransformer.php

@@ -5,13 +5,15 @@
 namespace phpDocumentor\Guides\Compiler\NodeTransformers\MenuNodeTransformers;
 
 use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Exception\DocumentEntryNotFound;
 use phpDocumentor\Guides\Nodes\DocumentTree\DocumentEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\InternalMenuEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\MenuEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\MenuNode;
 use phpDocumentor\Guides\Nodes\Node;
 
 use function assert;
+use function sprintf;
 
 class SubInternalMenuEntryNodeTransformer extends AbstractMenuEntryNodeTransformer
 {
@@ -31,6 +33,14 @@ protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNo
     {
         assert($entryNode instanceof InternalMenuEntryNode);
         $maxDepth = (int) $currentMenu->getOption('maxdepth', self::DEFAULT_MAX_LEVELS);
+        try {
+            $documentEntryOfMenuEntry = $compilerContext->getProjectNode()->getDocumentEntry($entryNode->getUrl());
+        } catch (DocumentEntryNotFound) {
+            $this->logger->warning(sprintf('Menu entry "%s" was not found in the document tree. Ignoring it. ', $entryNode->getUrl()), $compilerContext->getLoggerInformation());
+
+            return [];
+        }
+
         $documentEntryOfMenuEntry = $compilerContext->getProjectNode()->getDocumentEntry($entryNode->getUrl());
         $this->addSubEntries($currentMenu, $compilerContext, $entryNode, $documentEntryOfMenuEntry, $entryNode->getLevel() + 1, $maxDepth);
 

packages/guides/src/Exception/DocumentEntryNotFound.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\Exception;
+
+use Exception;
+
+final class DocumentEntryNotFound extends Exception
+{
+}

packages/guides/src/Nodes/ProjectNode.php

@@ -6,6 +6,7 @@
 
 use DateTimeImmutable;
 use Exception;
+use phpDocumentor\Guides\Exception\DocumentEntryNotFound;
 use phpDocumentor\Guides\Meta\CitationTarget;
 use phpDocumentor\Guides\Meta\InternalTarget;
 use phpDocumentor\Guides\Nodes\DocumentTree\DocumentEntryNode;
@@ -163,6 +164,7 @@ public function getRootDocumentEntry(): DocumentEntryNode
         throw new Exception('No root document entry was found');
     }
 
+    /** @throws DocumentEntryNotFound */
     public function getDocumentEntry(string $file): DocumentEntryNode
     {
         foreach ($this->documentEntries as $documentEntry) {
@@ -171,7 +173,7 @@ public function getDocumentEntry(string $file): DocumentEntryNode
             }
         }
 
-        throw new Exception('No document Entry found for file ' . $file);
+        throw new DocumentEntryNotFound('No document Entry found for file ' . $file);
     }
 
     /** @param DocumentEntryNode[] $documentEntries */

tests/Integration/tests/toctree/toctree-entry-not-found/expected/index.html

@@ -0,0 +1,17 @@
+<!-- content start -->
+    <div class="section" id="document-title">
+    <h1>Document Title</h1>
+
+            <div class="toc">
+            <p class="caption"><strong>Table of Contents</strong></p>
+    <ul class="menu-level">
+    <li class="toc-item"><a href="/page1.html#page-1">Page 1</a></li>
+
+    <li class="toc-item"><a href="/page2.html#page-2">Page 2</a></li>
+
+    </ul>
+</div>
+
+    </div>
+
+<!-- content end -->

tests/Integration/tests/toctree/toctree-entry-not-found/expected/logs/warning.log

@@ -0,0 +1 @@
+app.WARNING: Menu entry "page3" was not found in the document tree. Ignoring it.  {"rst-file":"index.rst"} []

tests/Integration/tests/toctree/toctree-entry-not-found/input/index.rst

@@ -0,0 +1,10 @@
+Document Title
+==============
+
+.. toctree::
+    :caption: **Table of Contents**
+    :titlesonly:
+
+    page1
+    page2
+    page3

tests/Integration/tests/toctree/toctree-entry-not-found/input/page1.rst

@@ -0,0 +1,8 @@
+Page 1
+======
+
+Chapter 1
+---------
+
+Chapter 2
+---------

tests/Integration/tests/toctree/toctree-entry-not-found/input/page2.rst

@@ -0,0 +1,4 @@
+Page 2
+======
+
+Lorem Ipsum Dolor