First iteration on option attributes

packages/guides-restructured-text/src/RestructuredText/Directives/Attributes/Option.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Directives\Attributes;
+
+use Attribute;
+use phpDocumentor\Guides\RestructuredText\Directives\OptionType;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final class Option
+{
+    public function __construct(
+        public readonly string $name,
+        public readonly OptionType $type = OptionType::String,
+        public readonly mixed $default = null,
+        public readonly string $description = '',
+        public readonly string|null $example = null,
+    ) {
+    }
+}
+

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

@@ -15,6 +15,7 @@
 
 use phpDocumentor\Guides\Nodes\GenericNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Directives\Attributes\Option;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
@@ -36,6 +37,9 @@
  */
 abstract class BaseDirective
 {
+    /** @var array<string, Option|null> Cache of Option attributes indexed by option name */
+    private array $optionAttributeCache;
+
     /**
      * Get the directive name
      */
@@ -94,4 +98,87 @@
     {
         return array_map(static fn (DirectiveOption $option): bool|float|int|string|null => $option->getValue(), $options);
     }
+
+    /**
+     * Gets an option value from a directive based on attribute configuration.
+     *
+     * Looks up the option in the directive and returns its value converted to the
+     * appropriate type based on the Option attribute defined on this directive class.
+     * If the option is not present in the directive, returns the default value from the attribute.
+     *
+     * @param Directive $directive The directive containing the options
+     * @param string $optionName The name of the option to retrieve
+     *
+     * @return mixed The option value converted to the appropriate type, or the default value
+     */
+    final protected function readOption(Directive $directive, string $optionName): mixed
+    {
+        $optionAttribute = $this->findOptionAttribute($optionName);
+
+        return $this->getOptionValue($directive, $optionAttribute);
+    }
+
+    final protected function readAllOptions(Directive $directive): array
+    {
+        $this->initialize();
+
+        return array_map(
+            fn (Option $option) => $this->getOptionValue($directive, $option),
+            $this->optionAttributeCache
+        );
+    }
+
+    private function getOptionValue(Directive $directive, Option|null $option): mixed
+    {
+        if ($option === null) {
+            return null;
+        }
+
+        if (!$directive->hasOption($option->name)) {
+            return $option->default;
+        }
+
+        $directiveOption = $directive->getOption($option->name);
+        $value = $directiveOption->getValue();
+
+        return match ($option->type) {
+            OptionType::Integer => (int) $value,
+            OptionType::Boolean => $value === null || filter_var($value, FILTER_VALIDATE_BOOL),
+            OptionType::String => (string) $value,
+            OptionType::Array => (array) $value,
+            default => $value,
+        };
+    }
+
+
+    /**
+     * Finds the Option attribute for the given option name on the current class.
+     *
+     * @param string $optionName The option name to look for
+     *
+     * @return Option|null The Option attribute if found, null otherwise
+     */
+    private function findOptionAttribute(string $optionName): ?Option
+    {
+        $this->initialize();
+
+        return $this->optionAttributeCache[$optionName] ?? null;
+    }
+
+    private function initialize(): void
+    {
+        if (isset($this->optionAttributeCache)) {
+            return;
+        }
+
+        $reflection = new \ReflectionClass($this);
+        $attributes = $reflection->getAttributes(Option::class);
+        $this->optionAttributeCache = [];
+        foreach ($attributes as $attribute) {
+            $option = $attribute->newInstance();
+            $this->optionAttributeCache[$option->name] = $option;
+        }
+    }
 }
+
+

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

@@ -16,6 +16,7 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
+use phpDocumentor\Guides\RestructuredText\Directives\Attributes\Option;
 use phpDocumentor\Guides\RestructuredText\Nodes\ConfvalNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
@@ -32,6 +33,11 @@
  *
  * https://sphinx-toolbox.readthedocs.io/en/stable/extensions/confval.html
  */
+#[Option(name: 'name', description: 'Id of the configuration value, used for linking to it.')]
+#[Option(name: 'type', description: 'Type of the configuration value, e.g. "string", "int", etc.')]
+#[Option(name: 'required', type: OptionType::Boolean, default: false, description: 'Whether the configuration value is required or not.')]
+#[Option(name: 'default', description: 'Default value of the configuration value, if any.')]
+#[Option(name: 'noindex', type: OptionType::Boolean, default: false, description: 'Whether the configuration value should not be indexed.')]
 final class ConfvalDirective extends SubDirective
 {
     public const NAME = 'confval';
@@ -80,16 +86,16 @@
         }
 
         if ($directive->hasOption('type')) {
-            $type = $this->inlineParser->parse($directive->getOptionString('type'), $blockContext);
+            $type = $this->inlineParser->parse($this->readOption($directive, 'type'), $blockContext);
         }
 
-        $required = $directive->getOptionBool('required');
+        $required = $this->readOption($directive, 'required');
 
         if ($directive->hasOption('default')) {
-            $default = $this->inlineParser->parse($directive->getOptionString('default'), $blockContext);
+            $default = $this->inlineParser->parse($this->readOption($directive, 'default'), $blockContext);
         }
 
-        $noindex = $directive->getOptionBool('noindex');
+        $noindex = $this->readOption($directive, 'noindex');
 
         foreach ($directive->getOptions() as $option) {
             if (in_array($option->getName(), ['type', 'required', 'default', 'noindex', 'name'], true)) {
@@ -99,6 +105,6 @@
             $additionalOptions[$option->getName()] = $this->inlineParser->parse($option->toString(), $blockContext);
         }
 
         return new ConfvalNode($id, $directive->getData(), $type, $required, $default, $additionalOptions, $collectionNode->getChildren(), $noindex);
     }
 }

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

@@ -17,6 +17,7 @@
 use phpDocumentor\Guides\Nodes\Menu\SectionMenuEntryNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
+use phpDocumentor\Guides\RestructuredText\Directives\Attributes\Option;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
@@ -25,6 +26,8 @@
  *
  * Displays a table of content of the current page
  */
+#[Option(name: 'local', type: OptionType::Boolean, description: 'If set, the table of contents will only include sections that are local to the current document.', default: false)]
+#[Option(name: 'depth', description: 'The maximum depth of the table of contents.')]
 final class ContentsDirective extends BaseDirective
 {
     public function __construct(
@@ -51,6 +54,6 @@
         return (new ContentMenuNode([new SectionMenuEntryNode($absoluteUrl)]))
             ->withOptions($this->optionsToArray($options))
             ->withCaption($directive->getDataNode())
-            ->withLocal($directive->hasOption('local'));
+            ->withLocal($this->readOption($directive, 'local'));
     }
 }

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

@@ -20,6 +20,7 @@
 use phpDocumentor\Guides\Nodes\Table\TableColumn;
 use phpDocumentor\Guides\Nodes\Table\TableRow;
 use phpDocumentor\Guides\Nodes\TableNode;
+use phpDocumentor\Guides\RestructuredText\Directives\Attributes\Option;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\RuleContainer;

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

@@ -16,9 +16,11 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\DocumentBlockNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Directives\Attributes\Option;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
+#[Option(name: 'identifier', description: 'The identifier of the document block')]
 final class DocumentBlockDirective extends SubDirective
 {
     public function getName(): string
@@ -39,7 +41,7 @@
 
         return new DocumentBlockNode(
             $collectionNode->getChildren(),
-            $identifier,
+            $this->readOption($directive, 'identifier'),
         );
     }
 }

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

@@ -18,6 +18,7 @@
 use phpDocumentor\Guides\Nodes\ImageNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
+use phpDocumentor\Guides\RestructuredText\Directives\Attributes\Option;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
@@ -33,6 +34,14 @@
  *
  *      Here is an awesome caption
  */
+#[Option(name: 'width', description: 'Width of the image in pixels')]
+#[Option(name: 'height', description: 'Height of the image in pixels')]
+#[Option(name: 'alt', description: 'Alternative text for the image')]
+#[Option(name: 'scale', description: 'Scale of the image, e.g. 0.5 for half size')]
+#[Option(name: 'target', description: 'Target for the image, e.g. a link to the image')]
+#[Option(name: 'class', description: 'CSS class to apply to the image')]
+#[Option(name: 'name', description: 'Name of the image, used for references')]
+#[Option(name: 'align', description: 'Alignment of the image, e.g. left, right, center')]
 final class FigureDirective extends SubDirective
 {
     public function __construct(

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

@@ -20,6 +20,7 @@
 use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
+use phpDocumentor\Guides\RestructuredText\Directives\Attributes\Option;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
@@ -37,6 +38,14 @@
  *      :width: 100
  *      :title: An image
  */
+#[Option(name: 'width', description: 'Width of the image in pixels')]
+#[Option(name: 'height', description: 'Height of the image in pixels')]
+#[Option(name: 'alt', description: 'Alternative text for the image')]
+#[Option(name: 'scale', description: 'Scale of the image, e.g. 0.5 for half size')]
+#[Option(name: 'target', description: 'Target for the image, e.g. a link to the image')]
+#[Option(name: 'class', description: 'CSS class to apply to the image')]
+#[Option(name: 'name', description: 'Name of the image, used for references')]
+#[Option(name: 'align', description: 'Alignment of the image, e.g. left, right, center')]
 final class ImageDirective extends BaseDirective
 {
     /** @see https://regex101.com/r/9dUrzu/3 */
@@ -67,8 +76,11 @@
             ),
         );
         if ($directive->hasOption('target')) {
-            $targetReference = (string) $directive->getOption('target')->getValue();
-            $node->setTarget($this->resolveLinkTarget($targetReference));
+            $node->setTarget(
+                $this->resolveLinkTarget(
+                    $this->readOption($directive, 'target')
+                ),
+            );
         }
 
         return $node;

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

@@ -17,6 +17,7 @@
 use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\LiteralBlockNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Directives\Attributes\Option;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\DocumentRule;
@@ -27,6 +28,8 @@
 use function sprintf;
 use function str_replace;
 
+#[Option(name: 'literal', description: 'If set, the contents will be rendered as a literal block.')]
+#[Option(name: 'code', description: 'If set, the contents will be rendered as a code block with the specified language.')]
 final class IncludeDirective extends BaseDirective
 {
     public function __construct(private readonly DocumentRule $startingRule)

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

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Directives;
+
+enum OptionType
+{
+    case String;
+    case Integer;
+    case Boolean;
+    case Array;
+}

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

@@ -14,10 +14,11 @@
 namespace phpDocumentor\Guides\RestructuredText\Directives;
 
 use phpDocumentor\Guides\Nodes\EmbeddedFrame;
+use phpDocumentor\Guides\RestructuredText\Directives\Attributes\Option;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
 use function array_filter;
 
 /**
  * This directive is used to embed a youtube video in the document.
@@ -36,6 +37,11 @@
  * - string allow The allow attribute of the iframe, default is 'encrypted-media; picture-in-picture; web-share'
  * - bool allowfullscreen Whether the video should be allowed to go fullscreen, default is true
  */
+#[Option('width', type: OptionType::Integer, default: 560, description: 'Width of the video')]
+#[Option('title', type: OptionType::String, description: 'Title of the video')]
+#[Option('height', type: OptionType::Integer, default: 315, description: 'Height of the video')]
+#[Option('allow', type: OptionType::String, default: 'encrypted-media; picture-in-picture; web-share', description: 'Allow attribute of the iframe')]
+#[Option('allowfullscreen', type: OptionType::Boolean, default: true, description: 'Whether the video should be allowed to go fullscreen')]
 final class YoutubeDirective extends BaseDirective
 {
     public function getName(): string
@@ -51,16 +57,6 @@
             'https://www.youtube-nocookie.com/embed/' . $directive->getData(),
         );
 
-        return $node->withOptions(
-            array_filter(
-                [
-                    'width' => $directive->getOption('width')->getValue() ?? 560,
-                    'title' => $directive->getOption('title')->getValue(),
-                    'height' => $directive->getOption('height')->getValue() ?? 315,
-                    'allow' => $directive->getOption('allow')->getValue() ?? 'encrypted-media; picture-in-picture; web-share',
-                    'allowfullscreen' => (bool) ($directive->getOption('allowfullscreen')->getValue() ?? true),
-                ],
-            ),
-        );
+        return $node->withOptions($this->readAllOptions($directive));
     }
 }