Merge pull request #651 from phpDocumentor/feature/confval

[FEATURE] Introduce confval directive

Author: linawolf

packages/guides-restructured-text/resources/config/guides-restructured-text.php

@@ -12,6 +12,7 @@
 use phpDocumentor\Guides\RestructuredText\Directives\CautionDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\ClassDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\CodeBlockDirective;
+use phpDocumentor\Guides\RestructuredText\Directives\ConfvalDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\ContainerDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\ContentsDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\CsvTableDirective;
@@ -169,6 +170,7 @@
                 CodeNodeOptionMapper::class,
             ),
         ])
+        ->set(ConfvalDirective::class)
         ->set(ContainerDirective::class)
         ->set(ContentsDirective::class)
         ->arg('$documentNameResolver', service(DocumentNameResolverInterface::class))

packages/guides-restructured-text/resources/template/html/body/directive/confval.html.twig

@@ -0,0 +1,21 @@
+<dl class="confval">
+    <dt id="{{ node.id }}">
+        <code class="sig-name descname"><span class="pre">{{ node.plainContent }}</span></code></dt>
+    <dd>
+        <div class="line-block">
+            {% if node.type != null %} <div class="line"><strong>Type:</strong>  {{ renderNode(node.type) }}</div>
+            {% endif -%}
+            {%- if node.required %} <div class="line"><strong>Required:</strong> true</div>
+            {% endif -%}
+            {% if node.default != null %} <div class="line"><strong>Type:</strong>  {{ renderNode(node.default) }}</div>
+            {% endif -%}
+            {%- for key, option in node.additionalOptions -%}
+                <div class="line"><strong>{{ key }}:</strong> {{  renderNode(option) }}</div>
+
+            {% endfor -%}
+        </div>
+        <div class="confval-description">
+            {{ renderNode(node.value) }}
+        </div>
+    </dd>
+</dl>

packages/guides-restructured-text/src/RestructuredText/DependencyInjection/ReStructuredTextExtension.php

@@ -6,6 +6,7 @@
 
 use phpDocumentor\Guides\NodeRenderers\TemplateNodeRenderer;
 use phpDocumentor\Guides\RestructuredText\DependencyInjection\Compiler\TextRolePass;
+use phpDocumentor\Guides\RestructuredText\Nodes\ConfvalNode;
 use phpDocumentor\Guides\RestructuredText\Nodes\OptionNode;
 use phpDocumentor\Guides\RestructuredText\Nodes\VersionChangeNode;
 use phpDocumentor\Guides\TemplateRenderer;
@@ -27,6 +28,7 @@ class ReStructuredTextExtension extends Extension implements PrependExtensionInt
     private const HTML = [
         VersionChangeNode::class => 'body/version-change.html.twig',
         OptionNode::class => 'body/directive/option.html.twig',
+        ConfvalNode::class => 'body/directive/confval.html.twig',
     ];
 
     /** @param mixed[] $configs */

packages/guides-restructured-text/src/RestructuredText/Directives/AbstractAdmonitionDirective.php

@@ -16,6 +16,7 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RestructuredText\Nodes\AdmonitionNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 
@@ -31,6 +32,7 @@ public function __construct(protected Rule $startingRule, private readonly strin
      * @param Directive $directive
      */
     final protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

packages/guides-restructured-text/src/RestructuredText/Directives/AbstractVersionChangeDirective.php

@@ -16,6 +16,7 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RestructuredText\Nodes\VersionChangeNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 
@@ -32,6 +33,7 @@ public function __construct(protected Rule $startingRule, private readonly strin
      * @param Directive $directive
      */
     final protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

packages/guides-restructured-text/src/RestructuredText/Directives/AdmonitionDirective.php

@@ -16,6 +16,7 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RestructuredText\Nodes\AdmonitionNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
 use function preg_replace;
@@ -45,6 +46,7 @@ public function getName(): string
      * @param Directive $directive
      */
     protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

packages/guides-restructured-text/src/RestructuredText/Directives/ClassDirective.php

@@ -8,6 +8,7 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\DocumentNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use Symfony\Component\String\Slugger\AsciiSlugger;
 
@@ -39,6 +40,7 @@ public function getAliases(): array
      * @param Directive $directive
      */
     protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

packages/guides-restructured-text/src/RestructuredText/Directives/ConfvalDirective.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Directives;
+
+use phpDocumentor\Guides\Nodes\CollectionNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\ReferenceResolvers\AnchorReducer;
+use phpDocumentor\Guides\RestructuredText\Nodes\ConfvalNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\InlineParser;
+use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
+use phpDocumentor\Guides\RestructuredText\TextRoles\GenericLinkProvider;
+
+use function boolval;
+use function in_array;
+
+/**
+ * The confval directive configuration values.
+ *
+ * https://sphinx-toolbox.readthedocs.io/en/stable/extensions/confval.html
+ */
+final class ConfvalDirective extends SubDirective
+{
+    public const NAME = 'confval';
+
+    /** @param Rule<CollectionNode> $startingRule */
+    public function __construct(
+        protected Rule $startingRule,
+        GenericLinkProvider $genericLinkProvider,
+        private readonly AnchorReducer $anchorReducer,
+        private readonly InlineParser $inlineParser,
+    ) {
+        parent::__construct($startingRule);
+
+        $genericLinkProvider->addGenericLink(self::NAME, ConfvalNode::LINK_TYPE);
+    }
+
+    public function getName(): string
+    {
+        return self::NAME;
+    }
+
+    /** {@inheritDoc}
+     *
+     * @param Directive $directive
+     */
+    protected function processSub(
+        BlockContext $blockContext,
+        CollectionNode $collectionNode,
+        Directive $directive,
+    ): Node|null {
+        $id = $this->anchorReducer->reduceAnchor($directive->getData());
+        $type = null;
+        $required = false;
+        $default = null;
+        $additionalOptions = [];
+        if ($directive->hasOption('type')) {
+            $type = $this->inlineParser->parse($directive->getOption('type')->toString(), $blockContext);
+        }
+
+        if ($directive->hasOption('required')) {
+            $required = boolval($directive->getOption('required'));
+        }
+
+        if ($directive->hasOption('default')) {
+            $type = $this->inlineParser->parse($directive->getOption('default')->toString(), $blockContext);
+        }
+
+        foreach ($directive->getOptions() as $option) {
+            if (in_array($option->getName(), ['type', 'required', 'default', 'noindex'], true)) {
+                continue;
+            }
+
+            $additionalOptions[$option->getName()] = $this->inlineParser->parse($option->toString(), $blockContext);
+        }
+
+        return new ConfvalNode($id, $directive->getData(), $type, $required, $default, $additionalOptions, $collectionNode->getChildren());
+    }
+}

packages/guides-restructured-text/src/RestructuredText/Directives/ContainerDirective.php

@@ -7,6 +7,7 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RestructuredText\Nodes\ContainerNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
 /**
@@ -32,6 +33,7 @@ public function getAliases(): array
      * @param Directive $directive
      */
     protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

packages/guides-restructured-text/src/RestructuredText/Directives/DocumentBlockDirective.php

@@ -7,6 +7,7 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\DocumentBlockNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
 class DocumentBlockDirective extends SubDirective
@@ -21,6 +22,7 @@ public function getName(): string
      * @param Directive $directive
      */
     protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {