phpDocumentor · linawolf · Feb 17, 2024 · Feb 12, 2024 · Feb 12, 2024 · Feb 12, 2024
diff --git a/docs/contributions/index.rst b/docs/contributions/index.rst
@@ -4,6 +4,13 @@
 Contributions
 =============
 
+.. toctree::
+    :glob:
+    :hidden:
+
+    *
+
+
 Clone the mono repository
 =========================
 

diff --git a/docs/index.rst b/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
diff --git a/packages/guides-markdown/src/Markdown/MarkupLanguageParser.php b/packages/guides-markdown/src/Markdown/MarkupLanguageParser.php
@@ -65,6 +65,7 @@ public function parse(ParserContext $parserContext, string $contents): DocumentN
     private function parseDocument(NodeWalker $walker, string $hash): DocumentNode
     {
         $document = new DocumentNode($hash, ltrim($this->getParserContext()->getCurrentAbsolutePath(), '/'));
+        $document->setOrphan(true);
         $this->document = $document;
 
         while ($event = $walker->next()) {

diff --git a/packages/guides/src/Compiler/CompilerContext.php b/packages/guides/src/Compiler/CompilerContext.php
@@ -73,6 +73,10 @@ public function getShadowTree(): TreeNode
     /** @return array<string, string> */
     public function getLoggerInformation(): array
     {
+        if (!isset($this->shadowTree)) {
+            return [];
+        }
+
         return [...$this->getDocumentNode()->getLoggerInformation()];
     }
 }
diff --git a/packages/guides/src/Compiler/Passes/ToctreeValidationPass.php b/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();
+    }
+}
diff --git a/tests/Functional/FunctionalTest.php b/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 = '';

diff --git a/tests/Integration/tests/anchor/anchor-ref-title-equals-title/input/overview.rst b/tests/Integration/tests/anchor/anchor-ref-title-equals-title/input/overview.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 
 ========
 Overview

diff --git a/tests/Integration/tests/anchor/anchor-to-page/input/rst-overview.rst b/tests/Integration/tests/anchor/anchor-to-page/input/rst-overview.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _rst-overview:
 
 Overview

diff --git a/tests/Integration/tests/anchor/anchor-to-page/input/sphinx-overview.rst b/tests/Integration/tests/anchor/anchor-to-page/input/sphinx-overview.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _sphinx-overview:
 
 Overview

diff --git a/tests/Integration/tests/anchor/anchor-to-title-on-another-page/input/overview.rst b/tests/Integration/tests/anchor/anchor-to-title-on-another-page/input/overview.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _rst-overview:
 
 Overview

diff --git a/tests/Integration/tests/anchor/anchor-within-text/input/rst-overview.rst b/tests/Integration/tests/anchor/anchor-within-text/input/rst-overview.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _rst-overview:
 
 RST Overview

diff --git a/tests/Integration/tests/anchor/anchor-within-text/input/sphinx-overview.rst b/tests/Integration/tests/anchor/anchor-within-text/input/sphinx-overview.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _sphinx-overview:
 
 Sphinx Overview

diff --git a/tests/Integration/tests/body-elements/citation/citation-page/input/citations.rst b/tests/Integration/tests/body-elements/citation/citation-page/input/citations.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==============
 Document Title
 ==============

diff --git a/.../Integration/tests/body-elements/footnote/footnotes-on-document/input/page1.rst b/.../Integration/tests/body-elements/footnote/footnotes-on-document/input/page1.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ======
 Page 1
 ======

diff --git a/tests/Integration/tests/directives/role-directive/input/someFile.rst b/tests/Integration/tests/directives/role-directive/input/someFile.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Some File
 ==========
 

diff --git a/tests/Integration/tests/hyperlink-to-page/input/page1.rst b/tests/Integration/tests/hyperlink-to-page/input/page1.rst
@@ -1,2 +1,4 @@
+:orphan:
+
 Page 1
 ======
diff --git a/tests/Integration/tests/hyperlink-to-page/input/subpages/index.rst b/tests/Integration/tests/hyperlink-to-page/input/subpages/index.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ..  _page1:
 
 Some file

diff --git a/tests/Integration/tests/hyperlink-to-page/input/subpages/subpage1.rst b/tests/Integration/tests/hyperlink-to-page/input/subpages/subpage1.rst
@@ -1,2 +1,4 @@
+:orphan:
+
 Subpage 1
 =========
diff --git a/tests/Integration/tests/images/figure-relative/input/index.rst b/tests/Integration/tests/images/figure-relative/input/index.rst
@@ -30,3 +30,10 @@ An image with relative paths
     :alt: Alternative text
 
     Description
+
+
+..  toctree::
+    :hidden:
+    :glob:
+
+    subfolder/*
diff --git a/tests/Integration/tests/images/figure-relative/input/subfolder/subpage.rst b/tests/Integration/tests/images/figure-relative/input/subfolder/subpage.rst
@@ -22,3 +22,9 @@ An image with relative paths
     :alt: Alternative text
 
     Description
+
+..  toctree::
+    :hidden:
+    :glob:
+
+    subfolder/*
diff --git a/tests/Integration/tests/images/image-absolute/input/index.rst b/tests/Integration/tests/images/image-absolute/input/index.rst
@@ -25,3 +25,10 @@ An image with relative paths
 .. image:: images/hero2-illustration.svg
     :width: 400
     :alt: Alternative text
+
+
+..  toctree::
+    :hidden:
+    :glob:
+
+    subfolder/*
diff --git a/tests/Integration/tests/images/image-relative/input/index.rst b/tests/Integration/tests/images/image-relative/input/index.rst
@@ -25,3 +25,9 @@ An image with relative paths
 .. image:: images/hero2-illustration.svg
     :width: 400
     :alt: Alternative text
+
+..  toctree::
+    :hidden:
+    :glob:
+
+    subfolder/*
diff --git a/tests/Integration/tests/images/image-relative/input/subfolder/subpage.rst b/tests/Integration/tests/images/image-relative/input/subfolder/subpage.rst
@@ -18,3 +18,10 @@ An image with relative paths
 .. image:: ../images/hero2-illustration.svg
     :width: 400
     :alt: Alternative text
+
+..  toctree::
+    :hidden:
+    :glob:
+
+    subfolder/*
+
diff --git a/tests/Integration/tests/meta/project-meta-global/input/a_page.rst b/tests/Integration/tests/meta/project-meta-global/input/a_page.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ======
 A Page
 ======

diff --git a/tests/Integration/tests/navigation/docref/input/subfolder/index.rst b/tests/Integration/tests/navigation/docref/input/subfolder/index.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============
 Subfolder index
 ===============

diff --git a/tests/Integration/tests/navigation/references/input/page.rst b/tests/Integration/tests/navigation/references/input/page.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Page 1
 *******
 

diff --git a/tests/Integration/tests/navigation/references/input/subfolder/index.rst b/tests/Integration/tests/navigation/references/input/subfolder/index.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============
 Subfolder index
 ===============

diff --git a/tests/Integration/tests/toctree/toctree-not-included/expected/index.html b/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 -->
diff --git a/tests/Integration/tests/toctree/toctree-not-included/expected/logs/warning.log b/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"} []
diff --git a/tests/Integration/tests/toctree/toctree-not-included/expected/overview.html b/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 -->
diff --git a/tests/Integration/tests/toctree/toctree-not-included/input/index.rst b/tests/Integration/tests/toctree/toctree-not-included/input/index.rst
@@ -0,0 +1,2 @@
+index
+=====
diff --git a/tests/Integration/tests/toctree/toctree-not-included/input/overview.rst b/tests/Integration/tests/toctree/toctree-not-included/input/overview.rst
@@ -0,0 +1,4 @@
+Overview
+========
+
+Lorem Ipsum Dolor
-Original file line number
+Diff line change
@@ -1,3 +1,5 @@
+    :orphan:
     ======
     Page 1
     ======
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
		@@ -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"} []