[FEATURE] Make migration of inventories possible

I had to drop support for non-stable prefered TYPO3 versions in migration. That would mean in such a case they are listed as single <inventroy> tags

Documentation-rendertest/Redirects/Index.rst

@@ -0,0 +1,15 @@
+..  include:: /Includes.rst.txt
+
+..  _redirects:
+
+=========
+Redirects
+=========
+
+*   :ref:`mod <t3tsconfig:pagemod>
+*   :ref:`mod <t3tsconfig/main:pagemod>
+*   :ref:`mod <t3tsconfig/13.4:pagemod>
+*   :ref:`mod <t3tsconfig/12.4:pagemod>
+
+
+*   :ref:`Create a menu with TypoScript <t3ts45:menu>`

packages/typo3-docs-theme/resources/config/typo3-docs-theme.php

@@ -20,6 +20,7 @@
 use T3Docs\Typo3DocsTheme\Api\Typo3ApiService;
 use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\CollectPrefixLinkTargetsTransformer;
 use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\ConfvalMenuNodeTransformer;
+use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\RedirectsNodeTransformer;
 use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\RemoveInterlinkSelfReferencesFromCrossReferenceNodeTransformer;
 use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\ReplacePermalinksNodeTransformer;
 use T3Docs\Typo3DocsTheme\Directives\ConfvalMenuDirective;
@@ -84,6 +85,8 @@
         ->bind('$startingRule', service(DirectiveContentRule::class))
         ->instanceof(BaseDirective::class)
         ->tag('phpdoc.guides.directive')
+        ->set(RedirectsNodeTransformer::class)
+        ->tag('phpdoc.guides.compiler.nodeTransformers')
         ->set(ReplacePermalinksNodeTransformer::class)
         ->tag('phpdoc.guides.compiler.nodeTransformers')
         ->set(CollectPrefixLinkTargetsTransformer::class)

packages/typo3-docs-theme/src/Compiler/NodeTransformers/RedirectsNodeTransformer.php

@@ -0,0 +1,68 @@
+<?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 T3Docs\Typo3DocsTheme\Compiler\NodeTransformers;
+
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
+use phpDocumentor\Guides\Compiler\NodeTransformer;
+use phpDocumentor\Guides\Nodes\Inline\CrossReferenceNode;
+use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\PrefixedLinkTargetNode;
+use T3Docs\Typo3DocsTheme\Inventory\Typo3VersionService;
+
+use function assert;
+
+/** @implements NodeTransformer<CrossReferenceNode> */
+final class RedirectsNodeTransformer implements NodeTransformer
+{
+    public function __construct(
+        private readonly Typo3VersionService $typo3VersionService
+    ) {}
+
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
+    {
+        return $node;
+    }
+
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
+    {
+        assert($node instanceof CrossReferenceNode);
+        if ($node->getInterlinkDomain() === '') {
+            return $node;
+        }
+        if ($node->getInterlinkDomain() === 't3ts45') {
+            $version = $this->typo3VersionService->getPreferredVersion();
+            if (!in_array($version, ['12.4', '13.4', 'main'], true)) {
+                return $node;
+            }
+            $prefix = '';
+            if ($node instanceof PrefixedLinkTargetNode) {
+                $prefix = $node->getPrefix();
+            }
+            assert(is_string($node->getValue()));
+            return new ReferenceNode('guide-' . $node->getTargetReference(), $node->getValue(), $node->getInterlinkDomain(), $node->getInterlinkGroup(), $prefix);
+        }
+        return $node;
+    }
+
+    public function supports(Node $node): bool
+    {
+        return $node instanceof CrossReferenceNode;
+    }
+
+    public function getPriority(): int
+    {
+        return 900;
+    }
+}

packages/typo3-docs-theme/src/Inventory/Typo3InventoryRepository.php

@@ -46,17 +46,16 @@ public function __construct(
         }
         foreach (DefaultInventories::cases() as $defaultInventory) {
             $id = $this->anchorNormalizer->reduceAnchor($defaultInventory->name);
-            $url = $defaultInventory->getUrl();
-            if (!str_contains($url, '{typo3_version}')) {
-                $this->addInventory($id, $url, false);
+            if (!$defaultInventory->isVersioned()) {
+                $this->addInventory($id, $defaultInventory->getUrl(''), false);
                 continue;
             }
             foreach (Typo3VersionMapping::cases() as $versionMapping) {
-                $mappedUrl = str_replace('{typo3_version}', $versionMapping->getVersion(), $url);
+                $mappedUrl = $defaultInventory->getUrl($versionMapping->getVersion());
                 $this->addInventory($id . '-' . $versionMapping->value, $mappedUrl, false);
             }
             $preferred = $this->typo3VersionService->getPreferredVersion();
-            $this->addInventory($id, str_replace('{typo3_version}', $preferred, $url), false);
+            $this->addInventory($id, $defaultInventory->getUrl($preferred), false);
         }
     }
 
@@ -109,7 +108,7 @@ private function loadInventoryFromComposerExtension(string $reducedKey, string $
             } elseif ($defaultInventory = DefaultInventories::tryFrom($match1)) {
                 // we do not have a composer name here but a default inventory with a version, for example "t3coreapi/12.4"
                 $version = $this->typo3VersionService->resolveCoreVersion($match2);
-                $inventoryUrl = str_replace('{typo3_version}', $version, $defaultInventory->getUrl());
+                $inventoryUrl = $defaultInventory->getUrl($version);
             } else {
                 $version ??= 'main';
                 $version = $this->typo3VersionService->resolveVersion($version);

packages/typo3-guides-cli/src/Migration/SettingsMigrator.php

@@ -133,7 +133,7 @@ private function createInventorySection(): array
             $this->convertedSettings++;
 
             if ($defaultInventory = DefaultInventories::tryFrom($id)) {
-                $defaultUrl = $defaultInventory->getUrl();
+                $defaultUrl = $defaultInventory->getUrl(Typo3VersionMapping::Stable->getVersion());
                 if ($url === $defaultUrl) {
                     continue;
                 } else {

packages/typo3-guides-cli/tests/unit/Migration/SettingsMigratorTest.php

@@ -195,7 +195,7 @@ class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
                 </guides>
                 EXPECTED,
         ];
-        yield 'with intersphinx default id, non-stable preferred TYPO3 version' => [
+        yield 'with intersphinx default id, first version is not preferred TYPO3 version' => [
             'legacySettings' => [
                 'intersphinx_mapping' => [
                     't3viewhelper' => 'https://docs.typo3.org/other/typo3/view-helper-reference/12.4/en-us/',
@@ -204,8 +204,8 @@ class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
             ],
             'expected' => <<<EXPECTED
                 <guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" links-are-relative="true" xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd">
-                    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension" typo3-core-preferred="12.4"/>
-                    <inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/13.4/en-us/"/>
+                    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension" typo3-core-preferred="stable"/>
+                    <inventory id="t3viewhelper" url="https://docs.typo3.org/other/typo3/view-helper-reference/12.4/en-us/"/>
                 </guides>
                 EXPECTED,
         ];

packages/typo3-version-handling/src/DefaultInventories.php

@@ -8,6 +8,7 @@ enum DefaultInventories: string
     //            also add them to `Documentation/Developer/InterlinkInventories.rst`.
     case t3docs = 't3docs';
     case changelog = 'changelog';
+    case t3ts45 = 't3ts45';
     case t3coreapi = 't3coreapi';
     case t3tca = 't3tca';
     case t3tsconfig = 't3tsconfig';
@@ -27,9 +28,59 @@ enum DefaultInventories: string
     case t3exceptions = 't3exceptions';
     case api = 'api';
 
+    public function isVersioned(): bool
+    {
+
+        return match ($this) {
+            // Main doc page, it is only deployed to main
+            DefaultInventories::t3docs => false,
 
-    public function getUrl(): string
+            // Changelog, it is only deployed to main
+            DefaultInventories::changelog => false,
+
+
+            // Team Guides, they are commonly not versioned
+            DefaultInventories::h2document => false,
+            DefaultInventories::t3content => false,
+            DefaultInventories::t3contribute => false,
+            DefaultInventories::t3writing => false,
+            DefaultInventories::t3org => false,
+
+            // Other
+            DefaultInventories::fluid => false,
+            DefaultInventories::t3renderguides => false,
+            DefaultInventories::t3exceptions => false,
+
+            default => true,
+        };
+    }
+
+    public function getUrl(string $version): string
     {
+        if ($version === 'main') {
+            switch ($this) {
+                case DefaultInventories::t3tsconfig:
+                    return DefaultInventories::t3tsref->getUrl($version);
+                case DefaultInventories::t3ts45:
+                    return DefaultInventories::t3tsref->getUrl($version);
+            }
+        }
+        if ($version === '13.4') {
+            switch ($this) {
+                case DefaultInventories::t3tsconfig:
+                    return DefaultInventories::t3tsref->getUrl($version);
+                case DefaultInventories::t3ts45:
+                    return DefaultInventories::t3tsref->getUrl($version);
+            }
+        }
+        if ($version === '12.4') {
+            switch ($this) {
+                case DefaultInventories::t3tsconfig:
+                    return DefaultInventories::t3tsref->getUrl($version);
+                case DefaultInventories::t3ts45:
+                    return DefaultInventories::t3tsref->getUrl($version);
+            }
+        }
         return match ($this) {
             // Main doc page, it is only deployed to main
             DefaultInventories::t3docs => 'https://docs.typo3.org/',
@@ -38,17 +89,20 @@ public function getUrl(): string
             DefaultInventories::changelog => 'https://docs.typo3.org/c/typo3/cms-core/main/en-us/',
 
             // Core Manuals
-            DefaultInventories::t3coreapi => 'https://docs.typo3.org/m/typo3/reference-coreapi/{typo3_version}/en-us/',
-            DefaultInventories::t3tca => 'https://docs.typo3.org/m/typo3/reference-tca/{typo3_version}/en-us/',
-            DefaultInventories::t3tsconfig => 'https://docs.typo3.org/m/typo3/reference-tsconfig/{typo3_version}/en-us/',
-            DefaultInventories::t3tsref => 'https://docs.typo3.org/m/typo3/reference-typoscript/{typo3_version}/en-us/',
-            DefaultInventories::t3viewhelper => 'https://docs.typo3.org/other/typo3/view-helper-reference/{typo3_version}/en-us/',
+            DefaultInventories::t3coreapi => 'https://docs.typo3.org/m/typo3/reference-coreapi/' . $version . '/en-us/',
+            DefaultInventories::t3tca => 'https://docs.typo3.org/m/typo3/reference-tca/' . $version . '/en-us/',
+            DefaultInventories::t3tsref => 'https://docs.typo3.org/m/typo3/reference-typoscript/' . $version . '/en-us/',
+            DefaultInventories::t3viewhelper => 'https://docs.typo3.org/other/typo3/view-helper-reference/' . $version . '/en-us/',
 
             // Official Core Tutorials and Guides
-            DefaultInventories::t3editors => 'https://docs.typo3.org/m/typo3/tutorial-editors/{typo3_version}/en-us/',
-            DefaultInventories::t3sitepackage => 'https://docs.typo3.org/m/typo3/tutorial-sitepackage/{typo3_version}/en-us/',
-            DefaultInventories::t3start => 'https://docs.typo3.org/m/typo3/tutorial-getting-started/{typo3_version}/en-us/',
-            DefaultInventories::t3translate => 'https://docs.typo3.org/m/typo3/guide-frontendlocalization/{typo3_version}/en-us/',
+            DefaultInventories::t3editors => 'https://docs.typo3.org/m/typo3/tutorial-editors/' . $version . '/en-us/',
+            DefaultInventories::t3sitepackage => 'https://docs.typo3.org/m/typo3/tutorial-sitepackage/' . $version . '/en-us/',
+            DefaultInventories::t3start => 'https://docs.typo3.org/m/typo3/tutorial-getting-started/' . $version . '/en-us/',
+            DefaultInventories::t3translate => 'https://docs.typo3.org/m/typo3/guide-frontendlocalization/' . $version . '/en-us/',
+
+            // Former Official manuals, redirected starting 12.4
+            DefaultInventories::t3tsconfig => 'https://docs.typo3.org/m/typo3/reference-tsconfig/' . $version . '/en-us/',
+            DefaultInventories::t3ts45 => 'https://docs.typo3.org/m/typo3/tutorial-typoscript-in-45-minutes/' . $version . '/en-us/',
 
 
             // Team Guides, they are commonly not versioned
@@ -63,7 +117,7 @@ public function getUrl(): string
             DefaultInventories::t3renderguides => 'https://docs.typo3.org/other/t3docs/render-guides/main/en-us/',
             DefaultInventories::t3exceptions => 'https://docs.typo3.org/m/typo3/reference-exceptions/main/en-us/',
 
-            DefaultInventories::api => 'https://api.typo3.org/{typo3_version}/',
+            DefaultInventories::api => 'https://api.typo3.org/' . $version . '/',
         };
     }
 

tests/Integration/tests/guides-inventories/expected/index.html

@@ -18,6 +18,7 @@ <h1>Title<a class="headerlink" href="#title" data-bs-toggle="modal" data-bs-targ
             <li>t3start</li>
             <li>t3tca</li>
             <li>t3translate</li>
+            <li>t3ts45</li>
             <li>t3tsconfig</li>
             <li>t3tsref</li>
             <li>t3viewhelper</li>