phpDocumentor · linawolf · Nov 3, 2023 · Nov 2, 2023
diff --git a/packages/guides-restructured-text/resources/config/guides-restructured-text.php b/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))

diff --git a/packages/guides-restructured-text/resources/template/html/body/directive/confval.html.twig b/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>
diff --git a/...-restructured-text/src/RestructuredText/DependencyInjection/ReStructuredTextExtension.php b/...-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 */

diff --git a/.../guides-restructured-text/src/RestructuredText/Directives/AbstractAdmonitionDirective.php b/.../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 {

diff --git a/...ides-restructured-text/src/RestructuredText/Directives/AbstractVersionChangeDirective.php b/...ides-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 {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/AdmonitionDirective.php b/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 {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/ClassDirective.php b/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 {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/ConfvalDirective.php b/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());
+    }
+}
diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/ContainerDirective.php b/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 {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/DocumentBlockDirective.php b/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 {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/EpigraphDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/EpigraphDirective.php
@@ -7,6 +7,7 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\Nodes\QuoteNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
 /**
@@ -28,6 +29,7 @@ public function getName(): string
      * @param Directive $directive
      */
     protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/FigureDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/FigureDirective.php
@@ -8,6 +8,7 @@
 use phpDocumentor\Guides\Nodes\FigureNode;
 use phpDocumentor\Guides\Nodes\ImageNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 
@@ -37,6 +38,7 @@ public function getName(): string
      * @param Directive $directive
      */
     protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/GeneralDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/GeneralDirective.php
@@ -8,6 +8,7 @@
 use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RestructuredText\Nodes\GeneralDirectiveNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
 /**
@@ -25,6 +26,7 @@ public function getName(): string
      * @param Directive $directive
      */
     protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/HighlightsDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/HighlightsDirective.php
@@ -7,6 +7,7 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\Nodes\QuoteNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
 /**
@@ -27,6 +28,7 @@ public function getName(): string
      * @param Directive $directive
      */
     protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/OptionDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/OptionDirective.php
@@ -8,6 +8,7 @@
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorReducer;
 use phpDocumentor\Guides\RestructuredText\Nodes\OptionNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 use phpDocumentor\Guides\RestructuredText\TextRoles\GenericLinkProvider;
@@ -47,6 +48,7 @@ public function getName(): string
      * @param Directive $directive
      */
     protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/PullQuoteDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/PullQuoteDirective.php
@@ -7,6 +7,7 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\Nodes\QuoteNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
 /**
@@ -28,6 +29,7 @@ public function getName(): string
      * @param Directive $directive
      */
     protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/ReplaceDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/ReplaceDirective.php
@@ -9,6 +9,7 @@
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\Nodes\ParagraphNode;
 use phpDocumentor\Guides\Nodes\ReplacementNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
 use function count;
@@ -30,6 +31,7 @@ public function getName(): string
      * @param Directive $directive
      */
     final protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/SidebarDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/SidebarDirective.php
@@ -16,6 +16,7 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RestructuredText\Nodes\SidebarNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
 /**
@@ -35,6 +36,7 @@ public function getName(): string
      * @param Directive $directive
      */
     protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/SubDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/SubDirective.php
@@ -38,7 +38,7 @@ final public function process(
             return null;
         }
 
-        $node = $this->processSub($collectionNode, $directive);
+        $node = $this->processSub($blockContext, $collectionNode, $directive);
 
         if ($node === null) {
             return null;
@@ -54,6 +54,7 @@ protected function getStartingRule(): Rule
     }
 
     protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/TableDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/TableDirective.php
@@ -7,6 +7,7 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\Nodes\TableNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 use Psr\Log\LoggerInterface;
@@ -49,6 +50,7 @@ public function getName(): string
 
     /** {@inheritDoc} */
     protected function processSub(
+        BlockContext $blockContext,
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {