Introduce prerendering options

This new pre rendering options allow extensions to do pre-rendering node
changes. This can be usefull for changes that depend on the output format
like links.

Author: jaapio

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

@@ -83,5 +83,5 @@ public function processNode(
         return $this->createNode($referenceTarget, $value);
     }
 
-    abstract protected function createNode(string $referenceName, string $referenceTarget): AbstractLinkInlineNode;
+    abstract protected function createNode(string $referenceTarget, string|null $referenceName): AbstractLinkInlineNode;
 }

packages/guides/resources/config/guides.php

@@ -18,13 +18,14 @@
 use phpDocumentor\Guides\NodeRenderers\InMemoryNodeRendererFactory;
 use phpDocumentor\Guides\NodeRenderers\NodeRendererFactory;
 use phpDocumentor\Guides\NodeRenderers\NodeRendererFactoryAware;
-use phpDocumentor\Guides\NodeRenderers\ReferenceResolvingNodeRendererFactory;
+use phpDocumentor\Guides\NodeRenderers\PreRenderers\PreNodeRendererFactory;
 use phpDocumentor\Guides\Parser;
 use phpDocumentor\Guides\ReferenceResolvers\DelegatingReferenceResolver;
 use phpDocumentor\Guides\ReferenceResolvers\DocReferenceResolver;
 use phpDocumentor\Guides\ReferenceResolvers\ExternalReferenceResolver;
 use phpDocumentor\Guides\ReferenceResolvers\InternalReferenceResolver;
 use phpDocumentor\Guides\ReferenceResolvers\ReferenceResolver;
+use phpDocumentor\Guides\ReferenceResolvers\ReferenceResolverPreRender;
 use phpDocumentor\Guides\ReferenceResolvers\RefReferenceResolver;
 use phpDocumentor\Guides\Renderer\HtmlRenderer;
 use phpDocumentor\Guides\Renderer\InMemoryRendererFactory;
@@ -141,10 +142,13 @@
         ])
         ->alias(NodeRendererFactory::class, InMemoryNodeRendererFactory::class)
 
-        ->set(ReferenceResolvingNodeRendererFactory::class)
+        ->set(PreNodeRendererFactory::class)
         ->decorate(NodeRendererFactory::class)
         ->arg('$innerFactory', service('.inner'))
-        ->arg('$referenceResolver', service(DelegatingReferenceResolver::class))
+        ->arg('$preRenderers', tagged_iterator('phpdoc.guides.prerenderer'))
+
+        ->set(ReferenceResolverPreRender::class)
+        ->tag('phpdoc.guides.prerenderer')
 
         ->set(InMemoryRendererFactory::class)
         ->arg('$renderSets', tagged_iterator('phpdoc.renderer.typerenderer'))

packages/guides/src/NodeRenderers/PreRenderers/PreNodeRenderer.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\NodeRenderers\PreRenderers;
+
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RenderContext;
+
+interface PreNodeRenderer
+{
+    public function supports(Node $node): bool;
+
+    public function execute(Node $node, RenderContext $renderContext): Node;
+}

packages/guides/src/NodeRenderers/PreRenderers/PreNodeRendererFactory.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\NodeRenderers\PreRenderers;
+
+use phpDocumentor\Guides\NodeRenderers\NodeRenderer;
+use phpDocumentor\Guides\NodeRenderers\NodeRendererFactory;
+use phpDocumentor\Guides\Nodes\Node;
+
+use function count;
+
+/**
+ * Decorator to add pre-rendering logic to node renderers.
+ */
+final class PreNodeRendererFactory implements NodeRendererFactory
+{
+    public function __construct(
+        private NodeRendererFactory $innerFactory,
+        /** @var iterable<PreNodeRenderer> */
+        private iterable $preRenderers,
+    ) {
+    }
+
+    public function get(Node $node): NodeRenderer
+    {
+        $preRenderers = [];
+        foreach ($this->preRenderers as $preRenderer) {
+            if (!$preRenderer->supports($node)) {
+                continue;
+            }
+
+            $preRenderers[] = $preRenderer;
+        }
+
+        if (count($preRenderers) === 0) {
+            return $this->innerFactory->get($node);
+        }
+
+        return new PreRenderer($this->innerFactory->get($node), $preRenderers);
+    }
+}

packages/guides/src/NodeRenderers/PreRenderers/PreRenderer.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\NodeRenderers\PreRenderers;
+
+use phpDocumentor\Guides\NodeRenderers\NodeRenderer;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RenderContext;
+
+/** @implements NodeRenderer<Node> */
+final class PreRenderer implements NodeRenderer
+{
+    public function __construct(
+        /** @var NodeRenderer<Node> */
+        private readonly NodeRenderer $nodeRenderer,
+        /** @var iterable<PreNodeRenderer> */
+        private readonly iterable $preNodeRenderers,
+    ) {
+    }
+
+    public function supports(Node $node): bool
+    {
+        return $this->nodeRenderer->supports($node);
+    }
+
+    public function render(Node $node, RenderContext $renderContext): string
+    {
+        foreach ($this->preNodeRenderers as $preNodeRenderer) {
+            $node = $preNodeRenderer->execute($node, $renderContext);
+        }
+
+        return $this->nodeRenderer->render($node, $renderContext);
+    }
+}

packages/guides/src/NodeRenderers/ReferenceResolverNodeRenderer.php

@@ -6,7 +6,6 @@
 
 use phpDocumentor\Guides\Nodes\Inline\LinkInlineNode;
 use phpDocumentor\Guides\RenderContext;
-use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
 use function parse_url;
 use function preg_match;

packages/guides/src/NodeRenderers/ReferenceResolvingNodeRendererFactory.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\ReferenceResolvers;
+
+use phpDocumentor\Guides\NodeRenderers\PreRenderers\PreNodeRenderer;
+use phpDocumentor\Guides\Nodes\Inline\LinkInlineNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RenderContext;
+use Webmozart\Assert\Assert;
+
+final class ReferenceResolverPreRender implements PreNodeRenderer
+{
+    public function __construct(private readonly DelegatingReferenceResolver $referenceResolver)
+    {
+    }
+
+    public function supports(Node $node): bool
+    {
+        return $node instanceof LinkInlineNode;
+    }
+
+    public function execute(Node $node, RenderContext $renderContext): Node
+    {
+        Assert::isInstanceOf($node, LinkInlineNode::class);
+        $this->referenceResolver->resolve($node, $renderContext);
+
+        return $node;
+    }
+}