Improve syntax

Author: alamirault

src/KernelFactory.php

@@ -103,7 +103,7 @@ private static function getReferences(BuildConfig $buildConfig): array
     {
         return [
             new SymfonyReferences\ClassReference($buildConfig->getSymfonyRepositoryUrl()),
-            new SymfonyReferences\FileReference($buildConfig->getSymfonyRepositoryUrl()),
+            new SymfonyReferences\GithubReference($buildConfig->getSymfonyVersion()),
             new SymfonyReferences\MethodReference($buildConfig->getSymfonyRepositoryUrl()),
             new SymfonyReferences\NamespaceReference($buildConfig->getSymfonyRepositoryUrl()),
             new SymfonyReferences\PhpFunctionReference($buildConfig->getPhpDocUrl()),

src/Reference/FileReference.php

@@ -0,0 +1,61 @@
+<?php
+
+/*
+ * This file is part of the Docs Builder package.
+ * (c) Ryan Weaver <[email protected]>
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace SymfonyDocsBuilder\Reference;
+
+use Doctrine\RST\Environment;
+use Doctrine\RST\References\Reference;
+use Doctrine\RST\References\ResolvedReference;
+use function Symfony\Component\String\u;
+
+class GithubReference extends Reference
+{
+    private $symfonyVersion;
+
+    public function __construct(string $symfonyVersion)
+    {
+        $this->symfonyVersion = $symfonyVersion;
+    }
+
+    public function getName(): string
+    {
+        return 'github';
+    }
+
+    public function resolve(Environment $environment, string $data): ResolvedReference
+    {
+        $match = u($data)->match('/(?<linkName>.+)::(?<githubRepository>.+):(?<relativePath>.+)::/');
+
+        if (!$match) {
+            throw new \RuntimeException(sprintf('Malformed method reference "%s" in file "%s"', $data, $environment->getCurrentFileName()));
+        }
+
+        $linkName = $match['linkName'];
+        $githubRepository = $match['githubRepository'];
+        $relativePath = $match['relativePath'];
+
+        $resolvedRelativePath = str_replace('{symfonyVersion}', $this->symfonyVersion, $relativePath);
+
+        $githubLink = sprintf(
+            'https://github.com/%s/blob/%s',
+            $githubRepository,
+            $resolvedRelativePath
+        );
+
+        return new ResolvedReference(
+            $environment->getCurrentFileName(),
+            $linkName,
+            $githubLink,
+            [],
+            [
+                'title' => $resolvedRelativePath,
+            ]
+        );
+    }
+}

src/Reference/GithubReference.php

@@ -211,8 +211,8 @@ public function parserUnitBlockProvider()
             'blockName' => 'references/class',
         ];
 
-        yield 'file-reference' => [
-            'blockName' => 'references/file',
+        yield 'github-reference' => [
+            'blockName' => 'references/github',
         ];
 
         yield 'namespace-reference' => [

tests/IntegrationTest.php

@@ -0,0 +1,3 @@
+<p><a href="https://github.com/symfony/symfony/blob/4.0/src/Symfony/Component/Notifier/Bridge/AmazonSns/README.md" class="reference external" title="4.0/src/Symfony/Component/Notifier/Bridge/AmazonSns/README.md" rel="external noopener noreferrer" target="_blank">First link</a></p>
+
+<p><a href="https://github.com/foo/bar/blob/4.0/src/baz" class="reference external" title="4.0/src/baz" rel="external noopener noreferrer" target="_blank">Link with branch substitution</a></p>

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

@@ -0,0 +1,3 @@
+:github:`First link ::symfony/symfony:4.0/src/Symfony/Component/Notifier/Bridge/AmazonSns/README.md::`
+
+:github:`Link with branch substitution ::foo/bar:{symfonyVersion}/src/baz::`