feature #161 Adding the "tabs" directive (weaverryan)

This PR was squashed before being merged into the main branch.

Discussion
----------

Adding the "tabs" directive

Hi!

This adds a "tabs" directive, based off of https://sphinx-tabs.readthedocs.io/en/latest/

Example:

```rst

.. tabs:: UX Installation

    .. tab:: Webpack Encore

        Webpack Encore stuff!

        .. code-block:: yaml

            I am yaml:

    .. tab:: AssetMapper

        AssetMapper stuff!

        And another paragraph.
```

This will render (with a little assistance from Javier) just like a "configuration block", except that you can put any content inside. My use-case is for some UX-related items where install steps will now be different if you're using Encore vs AssetMapper, and I think a tabbed setup will be better than 2 sections right after each other.

Feedback appreciated!

Commits
-------

200f906 Adding the "tabs" directive

Author: javiereguiluz

src/Directive/ConfigurationBlockDirective.php

@@ -66,6 +66,7 @@ public function processSub(Parser $parser, ?Node $document, string $variable, st
             'directives/configuration-block.html.twig',
             [
                 'blocks' => $blocks,
+                'title' => 'Configuration formats',
             ]
         );
 

src/Directive/TabDirective.php

@@ -0,0 +1,36 @@
+<?php
+
+/*
+ * This file is part of the Docs Builder package.
+ * (c) Ryan Weaver <[email protected]>
+ * 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;
+use SymfonyDocsBuilder\Node\TabNode;
+
+/**
+ * Directive that only appears within the "tabs" directive.
+ */
+class TabDirective extends SubDirective
+{
+    public function getName(): string
+    {
+        return 'tab';
+    }
+
+    public function processSub(Parser $parser, ?Node $document, string $variable, string $data, array $options): ?Node
+    {
+        $tabName = $data;
+        if (!$tabName) {
+            throw new \RuntimeException(sprintf('The "tab" directive requires a tab name: ".. tab:: Tab Name".'));
+        }
+
+        return new TabNode($document->getNodes(), $data);
+    }
+}

src/Directive/TabsDirective.php

@@ -0,0 +1,60 @@
+<?php
+
+/*
+ * This file is part of the Docs Builder package.
+ * (c) Ryan Weaver <[email protected]>
+ * 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;
+use SymfonyDocsBuilder\Node\TabNode;
+
+class TabsDirective extends SubDirective
+{
+    public function getName(): string
+    {
+        return 'tabs';
+    }
+
+    public function processSub(Parser $parser, ?Node $document, string $variable, string $data, array $options): ?Node
+    {
+        $tabsTitle = $data;
+        if (!$tabsTitle) {
+            throw new \RuntimeException(sprintf('The "tabs" directive requires a title: ".. tabs:: Title".'));
+        }
+
+        $blocks = [];
+        foreach ($document->getNodes() as $tabNode) {
+            if (!$tabNode instanceof TabNode) {
+                throw new \RuntimeException(sprintf('Only ".. tab::" content can appear within the "tabs" directive.'));
+            }
+
+            $content = '';
+            foreach ($tabNode->getNodes() as $node) {
+                $content .= $node->render();
+            }
+
+            $blocks[] = [
+                'hash' => hash('sha1', $tabNode->getTabName()),
+                'language_label' => $tabNode->getTabName(),
+                'language' => $tabNode->getSluggedTabName(),
+                'code' => $content,
+            ];
+         }
+
+        $wrapperDiv = $parser->renderTemplate(
+            'directives/configuration-block.html.twig',
+            [
+                'blocks' => $blocks,
+                'title' => $tabsTitle,
+            ]
+        );
+
+        return $parser->getNodeFactory()->createWrapperNode(null, $wrapperDiv, '</div>');
+    }
+}

src/KernelFactory.php

@@ -91,6 +91,8 @@ private static function getDirectives(): array
             new SymfonyDirectives\ScreencastDirective(),
             new SymfonyDirectives\SeeAlsoDirective(),
             new SymfonyDirectives\SidebarDirective(),
+            new SymfonyDirectives\TabDirective(),
+            new SymfonyDirectives\TabsDirective(),
             new SymfonyDirectives\TipDirective(),
             new SymfonyDirectives\TopicDirective(),
             new SymfonyDirectives\WarningDirective(),

src/Node/TabNode.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace SymfonyDocsBuilder\Node;
+
+use Doctrine\RST\Nodes\Node;
+
+/**
+ * Wraps nodes + options in a TabDirective.
+ */
+class TabNode extends Node
+{
+    /**
+     * @var Node[]
+     */
+    private array $nodes;
+
+    private string $tabName;
+
+    public function __construct(array $nodes, string $tabName)
+    {
+        $this->nodes = $nodes;
+        $this->tabName = $tabName;
+
+        parent::__construct();
+    }
+
+    public function getNodes(): array
+    {
+        return $this->nodes;
+    }
+
+    public function getTabName(): string
+    {
+        return $this->tabName;
+    }
+
+    public function getSluggedTabName(): string
+    {
+        return strtolower(str_replace(' ', '-', $this->tabName));
+    }
+}

src/Templates/default/html/directives/configuration-block.html.twig

@@ -1,5 +1,5 @@
 <div class="configuration-block">
-    <div role="tablist" aria-label="Configuration formats" class="configuration-tabs configuration-tabs-length-{{ blocks|length }}">
+    <div role="tablist" aria-label="{{ title }}" class="configuration-tabs configuration-tabs-length-{{ blocks|length }}">
         {% for block in blocks %}
             <button role="tab" type="button" data-language="{{ block.language }}"
                 aria-controls="{{ 'configuration-block-tabpanel-' ~ block.hash }}" aria-selected="{{ loop.first ? 'true' : 'false' }}"

tests/IntegrationTest.php

@@ -206,6 +206,10 @@ public function parserUnitBlockProvider()
             'blockName' => 'directives/sidebar-code-block-nested',
         ];
 
+        yield 'tabs' => [
+            'blockName' => 'directives/tabs',
+        ];
+
         yield 'class-reference' => [
             'blockName' => 'references/class',
         ];

tests/fixtures/expected/blocks/directives/tabs.html

@@ -0,0 +1,24 @@
+<div class="configuration-block">
+    <div role="tablist" aria-label="UX Installation" class="configuration-tabs configuration-tabs-length-2">
+        <button role="tab" type="button" data-language="webpack-encore" aria-controls="configuration-block-tabpanel-97a055193fa707f2025ee25bb469c74aa29b2c6c" aria-selected="true" data-active="true">
+            <span>Webpack Encore</span>
+        </button>
+        <button role="tab" type="button" data-language="assetmapper" aria-controls="configuration-block-tabpanel-1865de6b2b585de79e8700d7968050722e562c44" aria-selected="false" tabindex="-1">
+            <span>AssetMapper</span>
+        </button>
+    </div>
+
+    <div role="tabpanel" id="configuration-block-tabpanel-97a055193fa707f2025ee25bb469c74aa29b2c6c" aria-label="Webpack Encore" class="configuration-codeblock" data-language="webpack-encore" style="">
+        <p>Webpack Encore stuff!</p>
+        <div translate="no" data-loc="1" class="notranslate codeblock codeblock-length-sm codeblock-yaml">
+            <div class="codeblock-scroll">
+                <pre class="codeblock-lines">1</pre>
+                <pre class="codeblock-code"><code><span class="hljs-attr">I am yaml:</span></code></pre>
+            </div>
+        </div>
+    </div>
+    <div role="tabpanel" id="configuration-block-tabpanel-1865de6b2b585de79e8700d7968050722e562c44" aria-label="AssetMapper" class="configuration-codeblock" data-language="assetmapper" style="display: none">
+        <p>AssetMapper stuff!</p>
+        <p>And another paragraph.</p>
+    </div>
+</div>

tests/fixtures/source/blocks/directives/tabs.rst

@@ -0,0 +1,16 @@
+
+.. tabs:: UX Installation
+
+    .. tab:: Webpack Encore
+
+        Webpack Encore stuff!
+
+        .. code-block:: yaml
+
+            I am yaml:
+
+    .. tab:: AssetMapper
+
+        AssetMapper stuff!
+
+        And another paragraph.