[FEATURE] add configuration block directive

Add the implementation of the configuration block directive.
To make the implemtation more generic a configuration option is
introduced. This will allow the users to configure their own labels.

Co-authored-by: Wouter de Jong <[email protected]>

Author: jaapio

resources/config/guides-restructured-text.php

@@ -11,6 +11,7 @@
 use phpDocumentor\Guides\RestructuredText\Directives\CautionDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\ClassDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\CodeBlockDirective;
+use phpDocumentor\Guides\RestructuredText\Directives\ConfigurationBlockDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\ConfvalDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\ContainerDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\ContentsDirective;
@@ -115,6 +116,7 @@
 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
 
 use function Symfony\Component\DependencyInjection\Loader\Configurator\inline_service;
+use function Symfony\Component\DependencyInjection\Loader\Configurator\param;
 use function Symfony\Component\DependencyInjection\Loader\Configurator\service;
 use function Symfony\Component\DependencyInjection\Loader\Configurator\tagged_iterator;
 
@@ -175,6 +177,10 @@
             ),
         ])
         ->set(ConfvalDirective::class)
+        ->set(ConfigurationBlockDirective::class)
+        ->args([
+            '$languageLabels' => param('phpdoc.rst.code_language_labels'),
+        ])
         ->set(ContainerDirective::class)
         ->set(ContentsDirective::class)
         ->arg('$documentNameResolver', service(DocumentNameResolverInterface::class))

src/RestructuredText/DependencyInjection/ReStructuredTextExtension.php

@@ -8,26 +8,41 @@
 use phpDocumentor\Guides\RestructuredText\Nodes\ConfvalNode;
 use phpDocumentor\Guides\RestructuredText\Nodes\OptionNode;
 use phpDocumentor\Guides\RestructuredText\Nodes\VersionChangeNode;
+use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
+use Symfony\Component\Config\Definition\Builder\TreeBuilder;
+use Symfony\Component\Config\Definition\ConfigurationInterface;
 use Symfony\Component\Config\FileLocator;
 use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Extension\Extension;
 use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
 use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;
 
+use function assert;
 use function dirname;
 use function phpDocumentor\Guides\DependencyInjection\template;
 
-class ReStructuredTextExtension extends Extension implements PrependExtensionInterface, CompilerPassInterface
+final class ReStructuredTextExtension extends Extension implements
+    PrependExtensionInterface,
+    CompilerPassInterface,
+    ConfigurationInterface
 {
     /** @param mixed[] $configs */
     public function load(array $configs, ContainerBuilder $container): void
     {
+        $configuration = $this->getConfiguration($configs, $container);
+        $config = $this->processConfiguration($configuration, $configs);
         $loader = new PhpFileLoader(
             $container,
             new FileLocator(dirname(__DIR__, 3) . '/resources/config'),
         );
 
+        $normalizedLanguageLabels = [];
+        foreach ($config['code_language_labels'] ?? [] as $item) {
+            $normalizedLanguageLabels[$item['language']] = $item['label'];
+        }
+
+        $container->setParameter('phpdoc.rst.code_language_labels', $normalizedLanguageLabels);
         $loader->load('guides-restructured-text.php');
     }
 
@@ -55,4 +70,36 @@ public function process(ContainerBuilder $container): void
     {
         (new TextRolePass())->process($container);
     }
+
+    public function getConfigTreeBuilder(): TreeBuilder
+    {
+        $treeBuilder = new TreeBuilder('rst');
+        $rootNode = $treeBuilder->getRootNode();
+        assert($rootNode instanceof ArrayNodeDefinition);
+
+        $rootNode
+            ->fixXmlConfig('code_language_label', 'code_language_labels')
+            ->children()
+                ->arrayNode('code_language_labels')
+                    ->arrayPrototype()
+                        ->children()
+                            ->scalarNode('language')
+                                ->isRequired()
+                            ->end()
+                            ->scalarNode('label')
+                                ->isRequired()
+                            ->end()
+                        ->end()
+                    ->end()
+                ->end()
+            ->end();
+
+        return $treeBuilder;
+    }
+
+    /** @param mixed[] $config */
+    public function getConfiguration(array $config, ContainerBuilder $container): static
+    {
+        return $this;
+    }
 }

src/RestructuredText/Directives/ConfigurationBlockDirective.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Directives;
+
+use phpDocumentor\Guides\Nodes\CodeNode;
+use phpDocumentor\Guides\Nodes\CollectionNode;
+use phpDocumentor\Guides\Nodes\Configuration\ConfigurationBlockNode;
+use phpDocumentor\Guides\Nodes\Configuration\ConfigurationTab;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
+use Psr\Log\LoggerInterface;
+use Symfony\Component\String\Slugger\AsciiSlugger;
+use Symfony\Component\String\Slugger\SluggerInterface;
+
+use function assert;
+use function get_debug_type;
+
+final class ConfigurationBlockDirective extends SubDirective
+{
+    private SluggerInterface $slugger;
+
+    /**
+     * @param Rule<CollectionNode> $startingRule
+     * @param array<string, string> $languageLabels
+     */
+    public function __construct(
+        private LoggerInterface $logger,
+        Rule $startingRule,
+        private readonly array $languageLabels = [],
+    ) {
+        parent::__construct($startingRule);
+
+        $this->slugger = new AsciiSlugger();
+    }
+
+    public function getName(): string
+    {
+        return 'configuration-block';
+    }
+
+    protected function processSub(
+        BlockContext $blockContext,
+        CollectionNode $collectionNode,
+        Directive $directive,
+    ): Node|null {
+        $tabs = [];
+        foreach ($collectionNode->getValue() as $child) {
+            if (!$child instanceof CodeNode) {
+                $this->logger->warning('The ".. configuration-block::" directive only supports code blocks, "' . get_debug_type($child) . '" given.');
+
+                continue;
+            }
+
+            $language = $child->getLanguage();
+            assert($language !== null);
+
+            $label = $this->languageLabels[$language] ?? $this->slugger->slug($language, ' ')->title()->toString();
+
+            $tabs[] = new ConfigurationTab(
+                $label,
+                $this->slugger->slug($label)->lower()->toString(),
+                $child,
+            );
+        }
+
+        return new ConfigurationBlockNode($tabs);
+    }
+}