[Site] Document Toolkit recipes props and blocks

Author: Kocal

ux.symfony.com/composer.json

@@ -29,6 +29,7 @@
         "symfony/runtime": "^7.2",
         "symfony/serializer": "7.2.*",
         "symfony/stimulus-bundle": "2.x-dev",
+        "symfony/string": "7.2.*",
         "symfony/translation": "7.2.*",
         "symfony/twig-bundle": "7.2.*",
         "symfony/uid": "7.2.*",

ux.symfony.com/composer.lock

@@ -15,9 +15,12 @@
 use App\Service\Toolkit\ToolkitService;
 use League\CommonMark\CommonMarkConverter;
 use League\CommonMark\Extension\CommonMark\Node\Block\FencedCode;
+use League\CommonMark\Extension\DefaultAttributes\DefaultAttributesExtension;
 use League\CommonMark\Extension\ExternalLink\ExternalLinkExtension;
 use League\CommonMark\Extension\FrontMatter\FrontMatterExtension;
 use League\CommonMark\Extension\Mention\MentionExtension;
+use League\CommonMark\Extension\Table\Table;
+use League\CommonMark\Extension\Table\TableExtension;
 use Symfony\Component\DependencyInjection\Attribute\AsDecorator;
 
 /**
@@ -34,6 +37,11 @@ public function __construct(
     public function __invoke(): CommonMarkConverter
     {
         $converter = new CommonMarkConverter([
+            'default_attributes' => [
+                Table::class => [
+                    'class' => 'table',
+                ]
+            ],
             'mentions' => [
                 'github_handle' => [
                     'prefix' => '@',
@@ -52,9 +60,11 @@ public function __invoke(): CommonMarkConverter
         ]);
 
         $converter->getEnvironment()
+            ->addExtension(new DefaultAttributesExtension())
             ->addExtension(new ExternalLinkExtension())
             ->addExtension(new MentionExtension())
             ->addExtension(new FrontMatterExtension())
+            ->addExtension(new TableExtension())
             ->addRenderer(FencedCode::class, new CodeBlockRenderer($this->toolkitService))
         ;
 

ux.symfony.com/src/Service/CommonMark/ConverterFactory.php

@@ -22,9 +22,20 @@
 use Symfony\UX\Toolkit\Recipe\Recipe;
 use Symfony\UX\Toolkit\Recipe\RecipeType;
 use Symfony\UX\Toolkit\Registry\RegistryFactory;
+use function Symfony\Component\String\s;
 
 class ToolkitService
 {
+    /**
+     * @see https://regex101.com/r/3JXNX7/1
+     */
+    private const RE_API_PROPS = '/{#\s+@prop\s+(?P<name>\w+)\s+(?P<type>[^\s]+)\s+(?P<description>.+?)\s+#}/s';
+
+    /**
+     * @see https://regex101.com/r/jYjXpq/1
+     */
+    private const RE_API_BLOCKS = '/{#\s+@block\s+(?P<name>\w+)\s+(?P<description>.+?)\s+#}/s';
+
     public function __construct(
         #[Autowire(service: 'ux_toolkit.registry.registry_factory')]
         private readonly RegistryFactory $registryFactory,
@@ -142,6 +153,59 @@ public function renderInstallationSteps(ToolkitKitId $kitId, Recipe $recipe): st
         ]);
     }
 
+    public function renderApiReference(Recipe $recipe): string
+    {
+        $return = '';
+
+        foreach ($recipe->getFiles() as $file) {
+            $filePath = Path::join($recipe->absolutePath, $file->sourceRelativePathName);
+            if (!file_exists($filePath)) {
+                continue;
+            }
+
+            $fileContent = s(file_get_contents($filePath));
+
+            // Twig files...
+            if (str_ends_with($file->sourceRelativePathName, '.html.twig')) {
+                $props = $fileContent->match(self::RE_API_PROPS, PREG_SET_ORDER);
+                $blocks = $fileContent->match(self::RE_API_BLOCKS, PREG_SET_ORDER);
+
+                if ($props === [] && $blocks === []) {
+                    continue;
+                }
+
+                $componentName = s($file->sourceRelativePathName)
+                    ->replace('templates/components/', '')
+                    ->replace('.html.twig', '')
+                    ->replace('/', ':')
+                    ->toString();
+                $return .= '### '.htmlspecialchars($componentName).\PHP_EOL.\PHP_EOL;
+                if ([] !== $props) {
+                    $return .= "**Properties**\n\n";
+                    $return .= "| Name | Type | Description |\n";
+                    $return .= "| ---- | ---- | ----------- |\n";
+                    foreach ($props as $prop) {
+                        $return .= sprintf("| `%s` | `%s` | %s |\n", $prop['name'], $prop['type'], trim(preg_replace('/\s+/', ' ', $prop['description'])));
+                    }
+                    $return .= \PHP_EOL;
+                }
+                if ([] !== $blocks) {
+                    $return .= "**Blocks**\n\n";
+                    $return .= "| Name | Description |\n";
+                    $return .= "| ---- | ----------- |\n";
+                    foreach ($blocks as $block) {
+                        $return .= sprintf("| `%s` | %s |\n", $block['name'], trim(preg_replace('/\s+/', ' ', $block['description'])));
+                    }
+                    $return .= \PHP_EOL;
+                }
+            }
+        }
+
+        dump($return);
+
+        return $return;
+    }
+
     /**
      * @param non-empty-array<string, string> $tabs
      */

ux.symfony.com/src/Service/Toolkit/ToolkitService.php

@@ -53,6 +53,10 @@ public function getContent(): string
 
             ## Examples
 
+            %s
+
+            ## API Reference
+
             %s
             MARKDOWN,
             $this->component->manifest->name,
@@ -64,7 +68,8 @@ public function getContent(): string
                 $acc .= '### '.$exampleTitle.\PHP_EOL.$examples[$exampleTitle].\PHP_EOL;
 
                 return $acc;
-            }, '')
+            }, ''),
+            $this->toolkitService->renderApiReference($this->component),
         ));
     }