[FEATURE] Introduce Toctree caption

packages/guides-restructured-text/resources/config/guides-restructured-text.php

@@ -212,6 +212,7 @@
         ->set(TipDirective::class)
         ->set(TitleDirective::class)
         ->set(ToctreeDirective::class)
+        ->bind('$startingRule', service(InlineMarkupRule::class))
         ->set(MenuDirective::class)
         ->set(TodoDirective::class)
         ->set(UmlDirective::class)

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

@@ -4,11 +4,13 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Directives;
 
+use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 use phpDocumentor\Guides\Nodes\Menu\TocNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
+use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 use phpDocumentor\Guides\RestructuredText\Toc\ToctreeBuilder;
 
 /**
@@ -22,8 +24,11 @@
  */
 class ToctreeDirective extends BaseDirective
 {
-    public function __construct(private readonly ToctreeBuilder $toctreeBuilder)
-    {
+    /** @param Rule<InlineCompoundNode> $startingRule */
+    public function __construct(
+        private readonly ToctreeBuilder $toctreeBuilder,
+        private readonly Rule $startingRule,
+    ) {
     }
 
     public function getName(): string
@@ -46,6 +51,14 @@ public function process(
             $options,
         );
 
-        return (new TocNode($toctreeFiles))->withOptions($this->optionsToArray($options));
+        $tocNode =  (new TocNode($toctreeFiles))->withOptions($this->optionsToArray($options));
+
+        if (isset($options['caption'])) {
+            $blockContextOfCaption = new BlockContext($blockContext->getDocumentParserContext(), (string) $options['caption']->getValue());
+            $inlineNode = $this->startingRule->apply($blockContextOfCaption);
+            $tocNode = $tocNode->withCaption($inlineNode);
+        }
+
+        return $tocNode;
     }
 }

packages/guides/resources/template/html/body/menu/table-of-content.html.twig

@@ -1,3 +1,6 @@
 <div class="toc">
+    {% if node.caption %}
+        <p class="caption">{{ renderNode(node.caption) }}</p>
+    {% endif -%}
     {% include "body/menu/menu-level.html.twig" %}
 </div>

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

@@ -13,15 +13,11 @@
 
 namespace phpDocumentor\Guides\Nodes\Menu;
 
-use phpDocumentor\Guides\Nodes\InlineCompoundNode;
-
 use function is_scalar;
 
 /** @link https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents */
 class ContentMenuNode extends MenuNode
 {
-    private InlineCompoundNode|null $caption;
-
     public function getDepth(): int
     {
         if ($this->hasOption('depth') && is_scalar($this->getOption('depth'))) {
@@ -35,17 +31,4 @@ public function isPageLevelOnly(): bool
     {
         return false;
     }
-
-    public function getCaption(): InlineCompoundNode|null
-    {
-        return $this->caption;
-    }
-
-    public function withCaption(InlineCompoundNode|null $caption): ContentMenuNode
-    {
-        $that = clone $this;
-        $that->caption = $caption;
-
-        return $that;
-    }
 }

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

@@ -14,6 +14,7 @@
 namespace phpDocumentor\Guides\Nodes\Menu;
 
 use phpDocumentor\Guides\Nodes\CompoundNode;
+use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 use phpDocumentor\Guides\Nodes\Node;
 
 use const PHP_INT_MAX;
@@ -25,6 +26,7 @@
  */
 abstract class MenuNode extends CompoundNode
 {
+    private InlineCompoundNode|null $caption = null;
     protected const DEFAULT_DEPTH = PHP_INT_MAX;
 
     /** @var MenuEntryNode[] */
@@ -60,4 +62,17 @@ public function getMenuEntries(): array
     }
 
     abstract public function isPageLevelOnly(): bool;
+
+    public function getCaption(): InlineCompoundNode|null
+    {
+        return $this->caption;
+    }
+
+    public function withCaption(InlineCompoundNode|null $caption): static
+    {
+        $that = clone $this;
+        $that->caption = $caption;
+
+        return $that;
+    }
 }

tests/Integration/tests/toctree/toctree-caption/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-caption/input/index.rst

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

tests/Integration/tests/toctree/toctree-caption/input/page1.rst

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

tests/Integration/tests/toctree/toctree-caption/input/page2.rst

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