[FEATURE] Add local option to contents directive

resolves #901

Author: linawolf

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

@@ -50,6 +50,7 @@ public function process(
 
         return (new ContentMenuNode([new SectionMenuEntryNode($absoluteUrl)]))
             ->withOptions($this->optionsToArray($options))
-            ->withCaption($directive->getDataNode());
+            ->withCaption($directive->getDataNode())
+            ->withLocal($directive->hasOption('local'));
     }
 }

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

@@ -14,11 +14,13 @@
 namespace phpDocumentor\Guides\Compiler\NodeTransformers\MenuNodeTransformers;
 
 use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Nodes\DocumentTree\SectionEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\ContentMenuNode;
 use phpDocumentor\Guides\Nodes\Menu\MenuEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\MenuNode;
 use phpDocumentor\Guides\Nodes\Menu\SectionMenuEntryNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\SectionNode;
 
 use function assert;
 
@@ -45,12 +47,36 @@ protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNo
         assert($entryNode instanceof SectionMenuEntryNode);
         $depth = (int) $currentMenu->getOption('depth', self::DEFAULT_MAX_LEVELS - 1) + 1;
         $documentEntry = $compilerContext->getDocumentNode()->getDocumentEntry();
-        $newEntryNode = new SectionMenuEntryNode(
-            $documentEntry->getFile(),
-            $entryNode->getValue() ?? $documentEntry->getTitle(),
-            1,
-        );
-        $this->addSubSectionsToMenuEntries($documentEntry, $newEntryNode, $depth);
+        if ($currentMenu->isLocal()) {
+            $sectionNode = $compilerContext->getShadowTree()->getParent()?->getParent()?->getNode();
+            if (!$sectionNode instanceof SectionNode) {
+                $this->logger->error('Section of contents directive not found. ', $compilerContext->getLoggerInformation());
+
+                return [];
+            }
+
+            $sectionEntry = $documentEntry->findSectionEntry($sectionNode);
+            if (!$sectionEntry instanceof SectionEntryNode) {
+                $this->logger->error('Section of contents directive not found. ', $compilerContext->getLoggerInformation());
+
+                return [];
+            }
+
+            $newEntryNode = new SectionMenuEntryNode(
+                $documentEntry->getFile(),
+                $entryNode->getValue() ?? $sectionEntry->getTitle(),
+                1,
+                $sectionEntry->getId(),
+            );
+            $this->addSubSections($newEntryNode, $sectionEntry, $documentEntry, 1, $depth);
+        } else {
+            $newEntryNode = new SectionMenuEntryNode(
+                $documentEntry->getFile(),
+                $entryNode->getValue() ?? $documentEntry->getTitle(),
+                1,
+            );
+            $this->addSubSectionsToMenuEntries($documentEntry, $newEntryNode, $depth);
+        }
 
         return $newEntryNode->getSections();
     }

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

@@ -13,6 +13,7 @@
 
 namespace phpDocumentor\Guides\Nodes\DocumentTree;
 
+use phpDocumentor\Guides\Nodes\SectionNode;
 use phpDocumentor\Guides\Nodes\TitleNode;
 
 use function array_filter;
@@ -81,4 +82,22 @@ public function isRoot(): bool
     {
         return $this->isRoot;
     }
+
+    public function findSectionEntry(SectionNode $sectionNode): SectionEntryNode|null
+    {
+        foreach ($this->sections as $sectionEntryNode) {
+            if ($sectionNode->getId() === $sectionEntryNode->getId()) {
+                return $sectionEntryNode;
+            }
+        }
+
+        foreach ($this->sections as $sectionEntryNode) {
+            $subsection = $sectionEntryNode->findSectionEntry($sectionNode);
+            if ($subsection !== null) {
+                return $subsection;
+            }
+        }
+
+        return null;
+    }
 }

packages/guides/src/Nodes/DocumentTree/SectionEntryNode.php

@@ -14,6 +14,7 @@
 namespace phpDocumentor\Guides\Nodes\DocumentTree;
 
 use phpDocumentor\Guides\Nodes\DocumentNode;
+use phpDocumentor\Guides\Nodes\SectionNode;
 use phpDocumentor\Guides\Nodes\TitleNode;
 
 /** @extends EntryNode<DocumentNode> */
@@ -46,4 +47,22 @@ public function getChildren(): array
     {
         return $this->children;
     }
+
+    public function findSectionEntry(SectionNode $sectionNode): SectionEntryNode|null
+    {
+        foreach ($this->children as $sectionEntryNode) {
+            if ($sectionNode->getId() === $sectionEntryNode->getId()) {
+                return $sectionEntryNode;
+            }
+        }
+
+        foreach ($this->children as $sectionEntryNode) {
+            $subsection = $sectionEntryNode->findSectionEntry($sectionNode);
+            if ($subsection !== null) {
+                return $subsection;
+            }
+        }
+
+        return null;
+    }
 }

packages/guides/src/Nodes/Menu/ContentMenuNode.php

@@ -18,6 +18,8 @@
 /** @link https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents */
 final class ContentMenuNode extends MenuNode
 {
+    private bool $local = false;
+
     public function getDepth(): int
     {
         if ($this->hasOption('depth') && is_scalar($this->getOption('depth'))) {
@@ -31,4 +33,17 @@ public function isPageLevelOnly(): bool
     {
         return false;
     }
+
+    public function isLocal(): bool
+    {
+        return $this->local;
+    }
+
+    public function withLocal(bool $local): ContentMenuNode
+    {
+        $that = clone $this;
+        $that->local = $local;
+
+        return $that;
+    }
 }

tests/Integration/tests/navigation/contents/contents-local/expected/index.html

@@ -0,0 +1,37 @@
+<!-- content start -->
+    <div class="section" id="title">
+            <h1>Title</h1>
+
+    <p>Some Text</p>
+
+            <div class="section" id="properties">
+            <h2>Properties</h2>
+            <div class="contents">
+        <ul class="menu-level">
+    <li class="toc-item">
+    <a href="/index.html#additionalpreviewlanguages">additionalPreviewLanguages</a>
+
+
+</li>
+    <li class="toc-item">
+    <a href="/index.html#alertpopups">alertPopups</a>
+
+
+</li>
+    </ul>
+</div>
+            <div class="section" id="additionalpreviewlanguages">
+            <h3>additionalPreviewLanguages</h3>
+
+    <p>some text</p>
+
+    </div>
+            <div class="section" id="alertpopups">
+            <h3>alertPopups</h3>
+
+    <p>another text</p>
+
+    </div>
+    </div>
+    </div>
+<!-- content end -->

tests/Integration/tests/navigation/contents/contents-local/input/index.rst

@@ -0,0 +1,22 @@
+=====
+Title
+=====
+
+Some Text
+
+Properties
+==========
+
+..  contents::
+    :depth: 2
+    :local:
+
+additionalPreviewLanguages
+--------------------------
+
+some text
+
+alertPopups
+-----------
+
+another text