feature #140 Add support for figures with custom CSS classes (javiereguiluz, weaverryan)

This PR was merged into the main branch.

Discussion
----------

Add support for figures with custom CSS classes

In Symfony Fast Track book we use things like this:

```rst
.. figure:: screenshots/foo.png
    :alt: /
    :align: center
    :figclass: with-browser foo
```

Current parser translates it to:

```html
    <figure>
        <img src="" alt="/" align="center" figclass="with-browser foo">
    </figure>
```

But we need this:

```html
<div class="with-browser foo">
    <figure>
        <img src="" alt="/" align="center" figclass="with-browser foo">
    </figure>
</div>
```

We need that because `with-browser` class adds a "fake browser" window wrapping the image. But that fake browser is made with CSS `::before` and `::after` pseudo-elements, which don't work for `<figure>` or `<img>` and that's why we need the wrapping `<div>`.

Sadly, and as usual, I don't know what I'm doing and it doesn't work, so I'd need your help. Thanks!

Commits
-------

e2e384c unneeded logic
61761e5 cleanup and notes
b7f351b Overriding FigureDirective to fix lack of support for figclass
ba60661 -
a81fc94 -
b63440f -
676e8c7 Add support for figures with custom CSS classes

Author: javiereguiluz

src/Directive/FigureDirective.php

@@ -0,0 +1,64 @@
+<?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\SubDirective;
+use Doctrine\RST\Nodes\Node;
+use Doctrine\RST\Parser;
+
+/**
+ * Overridden to handle "figclass" properly.
+ */
+class FigureDirective extends SubDirective
+{
+    public function getName(): string
+    {
+        return 'figure';
+    }
+
+    /**
+     * @param string[] $options
+     */
+    public function processSub(
+        Parser $parser,
+        ?Node $document,
+        string $variable,
+        string $data,
+        array $options
+    ): ?Node {
+        $environment = $parser->getEnvironment();
+
+        $url = $environment->relativeUrl($data);
+
+        if ($url === null) {
+            throw new \Exception(sprintf('Could not get relative url for %s', $data));
+        }
+
+        $nodeFactory = $parser->getNodeFactory();
+
+        /* Start Custom Code */
+        $figClass = $options['figclass'] ?? null;
+        unset($options['figclass']);
+        /* End Custom Code */
+
+        $figureNode = $parser->getNodeFactory()->createFigureNode(
+            $nodeFactory->createImageNode($url, $options),
+            $document
+        );
+
+        /* Start Custom Code */
+        if ($figClass) {
+            $figureNode->setClasses(explode(' ', $figClass));
+        }
+        /* End Custom Code */
+
+        return $figureNode;
+    }
+}

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/Templates/default/html/figure.html.twig

@@ -0,0 +1,20 @@
+{#
+Overridden to fix lack of figclass support (class attribute on <figure)
+#}
+{% apply spaceless %}
+<figure
+    {% if figureNode.classes is not empty %}
+    class="{{ figureNode.classesString }}"
+    {% endif %}
+>
+    {{ figureNode.image.render()|raw }}
+
+    {% if figureNode.document %}
+        {% set caption = figureNode.document.render()|trim %}
+
+        {% if caption %}
+            <figcaption>{{ caption|raw }}</figcaption>
+        {% endif %}
+    {% endif %}
+</figure>
+{% endapply %}

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

@@ -15,3 +15,9 @@
 <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>
+
+<figure class="with-browser foo">
+    <img src="" alt="/" align="center">
+</figure>

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