[TASK] Issue warning if a document is not included in any toctree

Sphinx also issues this kind of warning. Project who do not
desire the warning could deactivate the pass

resolves TYPO3-Documentation/render-guides#332

Author: linawolf

docs/contributions/index.rst

@@ -4,6 +4,13 @@
 Contributions
 =============
 
+.. toctree::
+    :glob:
+    :hidden:
+
+    *
+
+
 Clone the mono repository
 =========================
 

docs/index.rst

@@ -35,9 +35,12 @@ are currently reading about::
 
 You will then find the rendered documentation in the directory output
 
-.. toctree::
+..  toctree::
+
     about
     usage
     configuration
+    components/index
     extension/index
     rst-reference/index
+    contributions/index

packages/guides/src/Compiler/CompilerContext.php

@@ -76,6 +76,7 @@ public function getLoggerInformation(): array
         if (!isset($this->shadowTree)) {
             return [];
         }
+
         return [...$this->getDocumentNode()->getLoggerInformation()];
     }
 }

packages/guides/src/Compiler/Passes/ToctreeValidationPass.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\Compiler\Passes;
+
+use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerPass;
+use phpDocumentor\Guides\Nodes\DocumentNode;
+use phpDocumentor\Guides\Nodes\DocumentTree\DocumentEntryNode;
+use phpDocumentor\Guides\Nodes\ProjectNode;
+use Psr\Log\LoggerInterface;
+
+final class ToctreeValidationPass implements CompilerPass
+{
+    public function __construct(
+        private readonly LoggerInterface $logger,
+    ) {
+    }
+
+    public function getPriority(): int
+    {
+        return 20; // must be run very late
+    }
+
+    /**
+     * @param DocumentNode[] $documents
+     *
+     * @return DocumentNode[]
+     */
+    public function run(array $documents, CompilerContext $compilerContext): array
+    {
+        $projectNode = $compilerContext->getProjectNode();
+
+        foreach ($documents as $document) {
+            if (!$this->isMissingInToctree($projectNode->getDocumentEntry($document->getFilePath()), $projectNode) || $document->isOrphan()) {
+                continue;
+            }
+
+            $this->logger->warning(
+                'Document "' . $document->getFilePath() . '" isn\'t included in any toctree. Include it in a `.. toctree::` directive or add `:orphan:` in the first line of the rst document',
+                $document->getLoggerInformation(),
+            );
+        }
+
+        return $documents;
+    }
+
+    public function isMissingInToctree(DocumentEntryNode $documentEntry, ProjectNode $projectNode): bool
+    {
+        return $documentEntry->getParent() === null && $documentEntry !== $projectNode->getRootDocumentEntry();
+    }
+}

tests/Functional/FunctionalTest.php

@@ -24,8 +24,10 @@
 use phpDocumentor\Guides\Compiler\Compiler;
 use phpDocumentor\Guides\Compiler\CompilerContext;
 use phpDocumentor\Guides\NodeRenderers\NodeRenderer;
+use phpDocumentor\Guides\Nodes\DocumentTree\DocumentEntryNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\Nodes\ProjectNode;
+use phpDocumentor\Guides\Nodes\TitleNode;
 use phpDocumentor\Guides\Parser;
 use phpDocumentor\Guides\RenderContext;
 use phpDocumentor\Guides\Settings\ProjectSettings;
@@ -102,10 +104,13 @@ public function testFunctional(
             $parser = $this->getContainer()->get(Parser::class);
             assert($parser instanceof Parser);
             $document = $parser->parse($rst);
+            $documentEntry = new DocumentEntryNode($document->getFilePath(), $document->getTitle() ?? TitleNode::fromString(''), true);
 
             $compiler = $this->getContainer()->get(Compiler::class);
             assert($compiler instanceof Compiler);
-            $compiler->run([$document], new CompilerContext(new ProjectNode()));
+            $projectNode = new ProjectNode();
+            $projectNode->setDocumentEntries([$documentEntry]);
+            $compiler->run([$document], new CompilerContext($projectNode));
 
             $inputFilesystem = new Filesystem(new MemoryAdapter());
             $inputFilesystem->write('img/test-image.jpg', 'Some image');
@@ -126,7 +131,7 @@ public function testFunctional(
                 $outfs = new Filesystem(new MemoryAdapter()),
                 '',
                 $format,
-                new ProjectNode(),
+                $projectNode,
             );
 
             $rendered = '';

tests/Integration/tests/toctree/toctree-not-included/expected/index.html

@@ -0,0 +1,7 @@
+<!-- content start -->
+    <div class="section" id="index">
+            <h1>index</h1>
+
+    </div>
+
+<!-- content end -->

tests/Integration/tests/toctree/toctree-not-included/expected/logs/warning.log

@@ -0,0 +1 @@
+app.WARNING: Document "overview" isn't included in any toctree. Include it in a `.. toctree::` directive or add `:orphan:` in the first line of the rst document {"rst-file":"overview.rst"} []

tests/Integration/tests/toctree/toctree-not-included/expected/overview.html

@@ -0,0 +1,8 @@
+<!-- content start -->
+    <div class="section" id="overview">
+            <h1>Overview</h1>
+
+            <p>Lorem Ipsum Dolor</p>
+    </div>
+
+<!-- content end -->

tests/Integration/tests/toctree/toctree-not-included/input/index.rst

@@ -0,0 +1,2 @@
+index
+=====