Add support for figures with custom CSS classes

Author: javiereguiluz

src/Directive/FigureDirective.php

@@ -0,0 +1,34 @@
+<?php
+
+/*
+ * This file is part of the Docs Builder package.
+ * (c) Ryan Weaver <ryan@symfonycasts.com>
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace SymfonyDocsBuilder\Directive;
+
+use Doctrine\RST\Directives\Directive;
+use Doctrine\RST\Nodes\FigureNode;
+use Doctrine\RST\Nodes\Node;
+use Doctrine\RST\Parser;
+
+class FigureDirective extends Directive
+{
+    public function getName(): string
+    {
+        return 'figure';
+    }
+
+    public function process(Parser $parser, ?Node $node, string $variable, string $data, array $options): void
+    {
+        if (!$node instanceof FigureNode) {
+            return;
+        }
+
+        // grab the "class" option and forward it onto the Node
+        // FigureRenderer can then use it when rendering
+        $node->setClasses(isset($options['class']) ? explode(' ', $options['class']) : []);
+    }
+}

src/KernelFactory.php

@@ -80,6 +80,7 @@ private static function getDirectives(): array
             new SymfonyDirectives\DangerDirective(),
             new SymfonyDirectives\DeprecatedDirective(),
             new SymfonyDirectives\ErrorDirective(),
+            new SymfonyDirectives\FigureDirective(),
             new SymfonyDirectives\HintDirective(),
             new SymfonyDirectives\ImportantDirective(),
             new SymfonyDirectives\IndexDirective(),

src/Renderers/FigureNodeRenderer.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Docs Builder package.
+ * (c) Ryan Weaver <ryan@symfonycasts.com>
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace SymfonyDocsBuilder\Renderers;
+
+use Doctrine\RST\Nodes\FigureNode;
+use Doctrine\RST\Renderers\NodeRenderer;
+use Doctrine\RST\Templates\TemplateRenderer;
+
+class FigureNodeRenderer implements NodeRenderer
+{
+    /** @var FigureNode */
+    private $figureNode;
+
+    /** @var TemplateRenderer */
+    private $templateRenderer;
+
+    public function __construct(FigureNode $figureNode, TemplateRenderer $templateRenderer)
+    {
+        $this->figureNode       = $figureNode;
+        $this->templateRenderer = $templateRenderer;
+    }
+
+    public function render(): string
+    {
+        var_dump('here');exit;
+        return $this->templateRenderer->render('figure.html.twig', [
+            'figureNode' => $this->figureNode,
+        ]);
+    }
+}

src/SymfonyHTMLFormat.php

@@ -13,6 +13,7 @@
 
 use Doctrine\RST\Formats\Format;
 use Doctrine\RST\Nodes\CodeNode;
+use Doctrine\RST\Nodes\FigureNode;
 use Doctrine\RST\Nodes\SpanNode;
 use Doctrine\RST\Renderers\CallableNodeRendererFactory;
 use Doctrine\RST\Renderers\NodeRendererFactory;
@@ -74,6 +75,15 @@ function (SpanNode $node) {
             }
         );
 
+        $nodeRendererFactories[FigureNode::class] = new CallableNodeRendererFactory(
+            function (FigureNode $node) {
+                return new Renderers\FigureNodeRenderer(
+                    $node,
+                    $this->templateRenderer
+                );
+            }
+        );
+
         return $nodeRendererFactories;
     }
 }

src/Templates/default/html/figure.html.twig

@@ -0,0 +1,13 @@
+{% if figureNode.classesString %}<div class="{{ figureNode.classesString }}">{% endif %}
+<figure>
+    {{ figureNode.image.render()|raw }}
+
+    {% if figureNode.document %}
+        {% set caption = figureNode.document.render()|trim %}
+
+        {% if caption %}
+            <figcaption>{{ caption|raw }}</figcaption>
+        {% endif %}
+    {% endif %}
+</figure>
+{% if figureNode.classesString %}</div>{% endif %}

tests/fixtures/expected/blocks/nodes/figure.html

@@ -15,3 +15,10 @@
 <div class="with-browser">
     <img src="" alt="A typical exception page in the development environment" align="center" class="some-class with-browser another-class">
 </div>
+
+<p>And RST figures use a different syntax to define their custom CSS classes:</p>
+<div class="with-browser foo">
+    <figure>
+        <img src="" alt="/" align="center" figclass="with-browser foo">
+    </figure>
+</div>

tests/fixtures/source/blocks/nodes/figure.rst

@@ -15,3 +15,10 @@ Some images use a special CSS class to wrap a fake browser around them:
    :alt: A typical exception page in the development environment
    :align: center
    :class: some-class with-browser another-class
+
+And RST figures use a different syntax to define their custom CSS classes:
+
+.. figure:: images/logo.png
+    :alt: /
+    :align: center
+    :figclass: with-browser foo