[FEATURE] Link to phpdomain API

Author: linawolf

Makefile

@@ -42,6 +42,10 @@ test-functional: ## Runs functional tests with phpunit/phpunit
 test-integration: ## Runs integration tests with phpunit/phpunit
 	$(PHP_BIN) vendor/bin/phpunit --testsuite=integration
 
+.PHONY: integration-baseline
+integration-baseline: ## Copies the output files of the integration tests into the expected directories, making a new baseline.
+	$(PHP_BIN) tools/integration-test-copy-baseline.php
+
 .PHONY: test-xml
 test-xml: ## Lint all guides.xml
 	./tools/xmllint.sh

packages/guides-restructured-text/resources/config/guides-restructured-text.php

@@ -106,6 +106,7 @@
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\TitleRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\TransitionRule;
 use phpDocumentor\Guides\RestructuredText\TextRoles\AbbreviationTextRole;
+use phpDocumentor\Guides\RestructuredText\TextRoles\ApiClassTextRole;
 use phpDocumentor\Guides\RestructuredText\TextRoles\DefaultTextRoleFactory;
 use phpDocumentor\Guides\RestructuredText\TextRoles\DocReferenceTextRole;
 use phpDocumentor\Guides\RestructuredText\TextRoles\GenericLinkProvider;
@@ -168,6 +169,7 @@
         ->set(GenericReferenceTextRole::class)
         ->set(ReferenceTextRole::class)
         ->set(AbbreviationTextRole::class)
+        ->set(ApiClassTextRole::class)
         ->set(MathTextRole::class)
         ->set(LiteralTextRole::class)
         ->set(SpanTextRole::class)

packages/guides-restructured-text/src/RestructuredText/TextRoles/AbstractReferenceTextRole.php

@@ -22,13 +22,15 @@ abstract class AbstractReferenceTextRole implements TextRole
 {
     use EmbeddedReferenceParser;
 
+    protected bool $useRawContent = false;
+
     public function processNode(
         DocumentParserContext $documentParserContext,
         string $role,
         string $content,
         string $rawContent,
     ): AbstractLinkInlineNode {
-        $referenceData = $this->extractEmbeddedReference($content);
+        $referenceData = $this->extractEmbeddedReference($this->useRawContent ? $rawContent : $content);
 
         return $this->createNode($referenceData->reference, $referenceData->text, $role);
     }

packages/guides-restructured-text/src/RestructuredText/TextRoles/ApiClassTextRole.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\RestructuredText\TextRoles;
+
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
+use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
+use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
+
+final class ApiClassTextRole extends AbstractReferenceTextRole
+{
+    final public const NAME = 'api-class';
+    final public const TYPE = 'api-class';
+    protected bool $useRawContent = true;
+
+    public function __construct(
+        private readonly GenericLinkProvider $genericLinkProvider,
+        private readonly AnchorNormalizer $anchorReducer,
+        private readonly InterlinkParser $interlinkParser,
+    ) {
+    }
+
+    public function getName(): string
+    {
+        return self::NAME;
+    }
+
+    /** @inheritDoc */
+    public function getAliases(): array
+    {
+        return [];
+    }
+
+    /** @return ReferenceNode */
+    protected function createNode(string $referenceTarget, string|null $referenceName, string $role): AbstractLinkInlineNode
+    {
+        $interlinkData = $this->interlinkParser->extractInterlink($referenceTarget);
+        $reference = $this->anchorReducer->reduceAnchor($interlinkData->reference);
+        $prefix = $this->genericLinkProvider->getLinkPrefix($role);
+
+        return new ReferenceNode($reference, $referenceName ?? '', $interlinkData->interlink, self::TYPE, $prefix);
+    }
+}

packages/guides/src/ReferenceResolvers/Interlink/InventoryLink.php

@@ -25,7 +25,7 @@ public function __construct(
         private string $path,
         private readonly string $title,
     ) {
-        if (preg_match('/^([a-zA-Z0-9-_.]+\/)*([a-zA-Z0-9-_.])+\.html(#[^#]*)?$/', $path) < 1) {
+        if (preg_match('/^([a-zA-Z0-9-_.]+\/)*([a-zA-Z0-9-_.]+)(\.html)?(#[^#]*)?$/', $path) < 1) {
             throw new InvalidInventoryLink('Inventory link "' . $path . '" has an invalid scheme. ', 1_671_398_986);
         }
     }

packages/guides/tests/unit/Interlink/InventoryLinkTest.php

@@ -54,13 +54,6 @@ public function testLinkMayContaintDot(): void
         self::assertEquals($inventoryLink->getPath(), $link);
     }
 
-    public function testPhpLinkThrowsError(): void
-    {
-        $link = 'Some/Path/SomeThing.php#anchor';
-        $this->expectException(InvalidInventoryLink::class);
-        new InventoryLink('', '', $link, '');
-    }
-
     public function testJavaScriptLinkThrowsError(): void
     {
         $link = 'javascript:alert()';

tests/Integration/tests/api/api-class-role/expected/index.html

@@ -0,0 +1,9 @@
+<!-- content start -->
+    <div class="section" id="document-title">
+            <h1>Document title</h1>
+
+    <p>See <a href="https://api.typo3.org/main/classes/TYPO3-CMS-Adminpanel-Controller-AjaxController.html">AjaxController</a> or
+<a href="https://api.typo3.org/main/classes/TYPO3-CMS-Adminpanel-Controller-MainController.html">that other controller</a>.</p>
+
+    </div>
+<!-- content end -->