feature #196 Update the class reference directive to support Symfony AI classes (javiereguiluz)

This PR was merged into the main branch.

Discussion
----------

Update the class reference directive to support Symfony AI classes

We need to publish Symfony AI docs on symfony.com ASAP. The GitHub links generated for the classes used in Symfony AI docs are wrong, so we must fix that somehow. This PR proposes a possible fix.

In the future we'll need something better ... but we'r ealso migrating to another doc builder project, so it's not worth it to try to make it perfect now.

Commits
-------

74df6be Update the class reference directive to support Symfony AI classes

Author: javiereguiluz

src/Reference/ClassReference.php

@@ -32,10 +32,27 @@ public function resolve(Environment $environment, string $data): ResolvedReferen
     {
         $className = u($data)->replace('\\\\', '\\');
 
+        if (str_starts_with($className, 'Symfony\\AI\\')) {
+            // Example:
+            // input: Symfony\AI\Agent\Memory\StaticMemoryProvider
+            // output: https://github.com/symfony/ai/blob/main/src/agent/src/Memory/StaticMemoryProvider.php
+
+            $classPath = $className->after('Symfony\\AI\\');
+            [$monorepoSubRepository, $classRelativePath] = $classPath->split('\\', 2);
+            // because of monorepo structure, the first part of the classpath needs to be slugged
+            // 'Agent' -> 'agent', 'AiBundle' -> 'ai-bundle', etc.
+            $monorepoSubRepository = u($monorepoSubRepository)->snake('-')->lower();
+            $classRelativePath = u($classRelativePath)->replace('\\', '/');
+
+            $url = \sprintf('https://github.com/symfony/ai/blob/main/src/%s/src/%s.php', $monorepoSubRepository, $classRelativePath);
+        } else {
+            $url = sprintf('%s/%s.php', $this->symfonyRepositoryUrl, $className->replace('\\', '/'));
+        }
+
         return new ResolvedReference(
             $environment->getCurrentFileName(),
             $className->afterLast('\\'),
-            sprintf('%s/%s.php', $this->symfonyRepositoryUrl, $className->replace('\\', '/')),
+            $url,
             [],
             [
                 'title' => $className,

tests/fixtures/expected/blocks/references/class.html

@@ -1 +1,3 @@
 <p><a href="https://github.com/symfony/symfony/blob/4.0/src/Symfony/Component/HttpKernel/DependencyInjection/ContainerAwareHttpKernel.php" class="reference external" title="Symfony\Component\HttpKernel\DependencyInjection\ContainerAwareHttpKernel" rel="external noopener noreferrer" target="_blank">ContainerAwareHttpKernel</a></p>
+
+<p><a href="https://github.com/symfony/ai/blob/main/src/agent/src/Memory/StaticMemoryProvider.php" class="reference external" title="Symfony\AI\Agent\Memory\StaticMemoryProvider" rel="external noopener noreferrer" target="_blank">StaticMemoryProvider</a></p>

tests/fixtures/source/blocks/references/class.rst

@@ -1,2 +1,4 @@
 
 :class:`Symfony\\Component\\HttpKernel\\DependencyInjection\\ContainerAwareHttpKernel`
+
+:class:`Symfony\\AI\\Agent\\Memory\\StaticMemoryProvider`