POC: Try to render docblocks in guides

config/services.yaml

@@ -222,3 +222,15 @@ services:
     phpDocumentor\Guides\Compiler\NodeTransformer\PHPReferenceNodeTransformer:
       tags:
         - { name: 'phpdoc.guides.compiler.nodeTransformers'}
+
+    phpDocumentor\Guides\Compiler\NodeTransformer\DocblockNodeTransformer:
+      tags:
+        - { name: 'phpdoc.guides.compiler.nodeTransformers' }
+
+    phpDocumentor\Guides\RestructuredText\Directives\Docblock:
+      tags:
+        - { name: 'phpdoc.guides.directive'}
+
+    phpDocumentor\Guides\NodeRenderer\DocblockRenderer:
+      tags:
+        - { name: 'phpdoc.guides.noderenderer.html' }

docs/guides/templates/twig.rst

@@ -163,6 +163,9 @@ route
     **type**: ``string``
     **default**: ``normal``
 
+.. docblock:: \phpDocumentor\Transformer\Writer\Twig\Extension::route()
+
+
 Renders a link to the generated page for the node. ``presentation`` can be set to ``'url'`` to render only the URL.
 
 sort_asc

src/phpDocumentor/Guides/Compiler/NodeTransformer/DocblockNodeTransformer.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace phpDocumentor\Guides\Compiler\NodeTransformer;
+
+use phpDocumentor\Compiler\DescriptorRepository;
+use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\NodeTransformer;
+use phpDocumentor\Guides\Nodes\DocblockNode;
+use phpDocumentor\Guides\Nodes\Node;
+
+class DocblockNodeTransformer implements NodeTransformer
+{
+    public function __construct(private readonly DescriptorRepository $descriptorRepository)
+    {
+    }
+
+    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    {
+        return $node;
+    }
+
+    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    {
+        if ($node instanceof DocblockNode === false) {
+            return $node;
+        }
+
+        $descriptor = $this->descriptorRepository->findDescriptorByFqsen(
+            $node->getFqsen(),
+        );
+
+        return $node->withDescriptor($descriptor);
+    }
+
+    public function supports(Node $node): bool
+    {
+        return $node instanceof DocblockNode;
+    }
+
+    public function getPriority(): int
+    {
+        return 3000;
+    }
+}

src/phpDocumentor/Guides/NodeRenderer/DocblockRenderer.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace phpDocumentor\Guides\NodeRenderer;
+
+use phpDocumentor\Guides\NodeRenderers\NodeRenderer;
+use phpDocumentor\Guides\Nodes\DocblockNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RenderContext;
+use phpDocumentor\Guides\TemplateRenderer;
+
+class DocblockRenderer implements NodeRenderer
+{
+    public function __construct(private readonly TemplateRenderer $renderer)
+    {
+    }
+
+    public function supports(Node $node): bool
+    {
+        return $node instanceof DocblockNode;
+    }
+
+    public function render(Node $node, RenderContext $renderContext): string
+    {
+        if ($node->getDescriptor() === null) {
+            return '';
+        }
+
+        return $this->renderer->renderTemplate(
+            $renderContext,
+            'components/method.html.twig',
+            ['method' => $node->getDescriptor()],
+        );
+    }
+}

src/phpDocumentor/Guides/Nodes/DocblockNode.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace phpDocumentor\Guides\Nodes;
+
+use phpDocumentor\Descriptor\Descriptor;
+use phpDocumentor\Reflection\Fqsen;
+
+final class DocblockNode extends AbstractNode
+{
+    private Descriptor|null $descriptor;
+
+    public function __construct(private Fqsen $fqsen)
+    {
+
+    }
+
+    public function getFqsen(): Fqsen
+    {
+        return $this->fqsen;
+    }
+
+    public function withDescriptor(Descriptor|null $descriptor): self
+    {
+        $that = clone $this;
+        $that->descriptor = $descriptor;
+
+        return $that;
+    }
+
+    public function getDescriptor(): Descriptor|null
+    {
+        return $this->descriptor;
+    }
+}

src/phpDocumentor/Guides/RestructuredText/Directives/Docblock.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace phpDocumentor\Guides\RestructuredText\Directives;
+
+use phpDocumentor\Guides\Nodes\DocblockNode;
+use phpDocumentor\Guides\Nodes\GenericNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Reflection\Fqsen;
+use Psr\Log\LoggerInterface;
+
+final class Docblock extends BaseDirective
+{
+    public function __construct(private LoggerInterface $logger)
+    {
+    }
+
+    public function getName(): string
+    {
+        return 'docblock';
+    }
+
+    public function processNode(BlockContext $blockContext, Directive $directive,): Node
+    {
+        try {
+            return new DocblockNode(new Fqsen($directive->getData()));
+        } catch (\InvalidArgumentException $e) {
+            $this->logger->warning(
+                sprintf(
+                    'Invalid docblock directive: %s',
+                    $e->getMessage()
+                )
+            );
+        }
+
+        return new GenericNode('invalid', $directive->getData());
+    }
+}

src/phpDocumentor/Transformer/Writer/Twig/Extension.php

@@ -359,11 +359,11 @@ public function getFilters(): array
             ),
             'route' => new TwigFilter(
                 'route',
-                fn (
-                    $value,
-                    string $presentation = LinkRenderer::PRESENTATION_NORMAL,
-                ) => $this->routeRenderer->render($value, $presentation),
-                ['is_safe' => ['all']],
+                $this->route(...),
+                [
+                    'needs_context' => true,
+                    'is_safe' => ['all']
+                ],
             ),
             'sort' => new TwigFilter('sort_*', $this->sort(...)),
             'sortByVisibility' => new TwigFilter('sortByVisibility', $this->sortByVisibility(...)),
@@ -507,4 +507,20 @@ static function (Descriptor $a, Descriptor $b) use ($visibilityOrder): int {
 
         return $iterator;
     }
+
+    /**
+     * Renders an url for a node or type.
+     *
+     * ```twig
+     * {{ node|route('class') }}
+     * ```
+     * @param mixed[] $context
+     * @param DescriptorAbstract|Fqsen|Reference\Reference|Path|string|iterable<mixed> $element
+     *
+     * @return string|list<string>
+     */
+    public function route($context, $element, string $presentation = LinkRenderer::PRESENTATION_NORMAL)
+    {
+        return $this->renderRoute($context, $element, $presentation);
+    }
 }