[BUGFIX] Make links to special objects prefixable

If we have both an anchor like '.. _demo:' and
a confval of the same name we would get duplicate id's and the links to those two elements could not be distinguished. Sphinx solves this by prefixing all confval links with "confval-".

Therefore, I introduce the possibility of prefixing links to distinguished linkable objects.

related #924

releases: main, 1.0

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 id="{{ node.anchor }}">
         <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

packages/guides-restructured-text/src/RestructuredText/Nodes/ConfvalNode.php

@@ -15,8 +15,8 @@
 
 use phpDocumentor\Guides\Nodes\CompoundNode;
 use phpDocumentor\Guides\Nodes\InlineCompoundNode;
-use phpDocumentor\Guides\Nodes\LinkTargetNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\PrefixedLinkTargetNode;
 
 /**
  * The confval directive configuration values.
@@ -25,9 +25,10 @@
  *
  * @extends CompoundNode<Node>
  */
-final class ConfvalNode extends CompoundNode implements LinkTargetNode
+final class ConfvalNode extends CompoundNode implements PrefixedLinkTargetNode
 {
     public const LINK_TYPE = 'std:confval';
+    public const LINK_PREFIX = 'confval-';
 
     /**
      * @param list<Node> $value
@@ -60,6 +61,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 +91,9 @@ public function getAdditionalOptions(): array
     {
         return $this->additionalOptions;
     }
+
+    public function getPrefix(): string
+    {
+        return self::LINK_PREFIX;
+    }
 }

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,7 @@
 use phpDocumentor\Guides\Nodes\LinkTargetNode;
 use phpDocumentor\Guides\Nodes\MultipleLinkTargetsNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\PrefixedLinkTargetNode;
 use phpDocumentor\Guides\Nodes\SectionNode;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
 use Psr\Log\LoggerInterface;
@@ -97,13 +98,19 @@ public function enterNode(Node $node, CompilerContext $compilerContext): 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/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/Inline/ReferenceNode.php

@@ -37,6 +37,7 @@ public function __construct(
         string $value = '',
         private readonly string $interlinkDomain = '',
         private readonly string $linkType = SectionNode::STD_LABEL,
+        private readonly string $prefix = '',
     ) {
         parent::__construct(self::TYPE, $targetReference, $value);
     }
@@ -62,6 +63,11 @@ public function getDebugInformation(): array
 
     public function getInterlinkGroup(): string
     {
-        return 'std:label';
+        return $this->linkType;
+    }
+
+    public function getPrefix(): string
+    {
+        return $this->prefix;
     }
 }

packages/guides/src/Nodes/PrefixedLinkTargetNode.php

@@ -0,0 +1,19 @@
+<?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\Nodes;
+
+interface PrefixedLinkTargetNode extends LinkTargetNode
+{
+    public function getPrefix(): string;
+}

packages/guides/src/ReferenceResolvers/AnchorReferenceResolver.php

@@ -46,7 +46,7 @@ public function resolve(LinkInlineNode $node, RenderContext $renderContext, Mess
             return false;
         }
 
-        $node->setUrl($this->urlGenerator->generateCanonicalOutputUrl($renderContext, $target->getDocumentPath(), $target->getAnchor()));
+        $node->setUrl($this->urlGenerator->generateCanonicalOutputUrl($renderContext, $target->getDocumentPath(), $target->getPrefix() . $target->getAnchor()));
         if ($node->getValue() === '') {
             $node->setValue($target->getTitle() ?? '');
         }