Merge branch 'main' into task/complex-grid-table

Author: linawolf

packages/guides-restructured-text/resources/template/html/body/directive/confval.html.twig

@@ -1,5 +1,5 @@
 <dl class="confval">
-    <dt id="{{ node.id }}">
+    <dt {%- if node.isNoindex == false %} id="{{ node.anchor }}"{% endif %}>
         <code class="sig-name descname"><span class="pre">{{ node.plainContent }}</span></code></dt>
     <dd>
         <div class="line-block">

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

@@ -44,7 +44,7 @@ public function __construct(
     ) {
         parent::__construct($startingRule);
 
-        $genericLinkProvider->addGenericLink(self::NAME, ConfvalNode::LINK_TYPE);
+        $genericLinkProvider->addGenericLink(self::NAME, ConfvalNode::LINK_TYPE, ConfvalNode::LINK_PREFIX);
     }
 
     public function getName(): string
@@ -83,6 +83,8 @@ protected function processSub(
             $type = $this->inlineParser->parse($directive->getOption('default')->toString(), $blockContext);
         }
 
+        $noindex = $directive->hasOption('noindex');
+
         foreach ($directive->getOptions() as $option) {
             if (in_array($option->getName(), ['type', 'required', 'default', 'noindex', 'name'], true)) {
                 continue;
@@ -91,6 +93,6 @@ protected function processSub(
             $additionalOptions[$option->getName()] = $this->inlineParser->parse($option->toString(), $blockContext);
         }
 
-        return new ConfvalNode($id, $directive->getData(), $type, $required, $default, $additionalOptions, $collectionNode->getChildren());
+        return new ConfvalNode($id, $directive->getData(), $type, $required, $default, $additionalOptions, $collectionNode->getChildren(), $noindex);
     }
 }

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-restructured-text/src/RestructuredText/Nodes/ConfvalNode.php

@@ -17,6 +17,8 @@
 use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 use phpDocumentor\Guides\Nodes\LinkTargetNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\OptionalLinkTargetsNode;
+use phpDocumentor\Guides\Nodes\PrefixedLinkTargetNode;
 
 /**
  * The confval directive configuration values.
@@ -25,9 +27,10 @@
  *
  * @extends CompoundNode<Node>
  */
-final class ConfvalNode extends CompoundNode implements LinkTargetNode
+final class ConfvalNode extends CompoundNode implements LinkTargetNode, OptionalLinkTargetsNode, PrefixedLinkTargetNode
 {
     public const LINK_TYPE = 'std:confval';
+    public const LINK_PREFIX = 'confval-';
 
     /**
      * @param list<Node> $value
@@ -41,6 +44,7 @@ public function __construct(
         private readonly InlineCompoundNode|null $default = null,
         private readonly array $additionalOptions = [],
         array $value = [],
+        private readonly bool $noindex = false,
     ) {
         parent::__construct($value);
     }
@@ -60,6 +64,11 @@ public function getId(): string
         return $this->id;
     }
 
+    public function getAnchor(): string
+    {
+        return self::LINK_PREFIX . $this->id;
+    }
+
     public function getLinkText(): string
     {
         return $this->plainContent;
@@ -85,4 +94,14 @@ public function getAdditionalOptions(): array
     {
         return $this->additionalOptions;
     }
+
+    public function getPrefix(): string
+    {
+        return self::LINK_PREFIX;
+    }
+
+    public function isNoindex(): bool
+    {
+        return $this->noindex;
+    }
 }

packages/guides-restructured-text/src/RestructuredText/TextRoles/GenericLinkProvider.php

@@ -30,10 +30,13 @@ final class GenericLinkProvider
     private array $textRoleLinkTypeMapping = [
         'ref' => SectionNode::STD_LABEL,
     ];
+    /** @var array<string, string> */
+    private array $prefixLinkTypeMapping = ['ref' => ''];
 
-    public function addGenericLink(string $textRole, string $linkType): void
+    public function addGenericLink(string $textRole, string $linkType, string $prefix = ''): void
     {
         $this->textRoleLinkTypeMapping[$textRole] = $linkType;
+        $this->prefixLinkTypeMapping[$textRole] = $prefix;
     }
 
     /** @return string[] */
@@ -46,4 +49,9 @@ public function getLinkType(string $textRole): string
     {
         return $this->textRoleLinkTypeMapping[$textRole] ?? SectionNode::STD_LABEL;
     }
+
+    public function getLinkPrefix(string $textRole): string
+    {
+        return $this->prefixLinkTypeMapping[$textRole] ?? '';
+    }
 }

packages/guides-restructured-text/src/RestructuredText/TextRoles/GenericReferenceTextRole.php

@@ -46,7 +46,8 @@ protected function createNode(string $referenceTarget, string|null $referenceNam
         $linkType = $this->genericLinkProvider->getLinkType($role);
         $interlinkData = $this->interlinkParser->extractInterlink($referenceTarget);
         $reference = $this->anchorReducer->reduceAnchor($interlinkData->reference);
+        $prefix = $this->genericLinkProvider->getLinkPrefix($role);
 
-        return new ReferenceNode($reference, $referenceName ?? '', $interlinkData->interlink, $linkType);
+        return new ReferenceNode($reference, $referenceName ?? '', $interlinkData->interlink, $linkType, $prefix);
     }
 }

packages/guides/src/Compiler/NodeTransformers/CollectLinkTargetsTransformer.php

@@ -21,6 +21,8 @@
 use phpDocumentor\Guides\Nodes\LinkTargetNode;
 use phpDocumentor\Guides\Nodes\MultipleLinkTargetsNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\OptionalLinkTargetsNode;
+use phpDocumentor\Guides\Nodes\PrefixedLinkTargetNode;
 use phpDocumentor\Guides\Nodes\SectionNode;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
 use Psr\Log\LoggerInterface;
@@ -94,16 +96,26 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         }
 
         if ($node instanceof LinkTargetNode) {
+            if ($node instanceof OptionalLinkTargetsNode && $node->isNoindex()) {
+                return $node;
+            }
+
             $currentDocument = $this->documentStack->top();
             Assert::notNull($currentDocument);
             $anchor = $this->anchorReducer->reduceAnchor($node->getId());
+            $prefix = '';
+            if ($node instanceof PrefixedLinkTargetNode) {
+                $prefix = $node->getPrefix();
+            }
+
             $this->addLinkTargetToProject(
                 $compilerContext,
                 new InternalTarget(
                     $currentDocument->getFilePath(),
                     $anchor,
                     $node->getLinkText(),
                     $node->getLinkType(),
+                    $prefix,
                 ),
             );
             if ($node instanceof MultipleLinkTargetsNode) {

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/Meta/InternalTarget.php

@@ -24,6 +24,7 @@ public function __construct(
         protected string $anchorName,
         private readonly string|null $title = null,
         private readonly string $linkType = SectionNode::STD_LABEL,
+        private readonly string $prefix = '',
     ) {
     }
 
@@ -63,4 +64,9 @@ public function getLinkType(): string
     {
         return $this->linkType;
     }
+
+    public function getPrefix(): string
+    {
+        return $this->prefix;
+    }
 }

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;
+    }
 }