Merge branch 'main' into feature/external-menu

Author: linawolf

docs/contributions/index.rst

@@ -7,6 +7,15 @@ Contributions
 Clone the mono repository
 =========================
 
+This project uses a :doc:`mono repository </contributions/monorepository-layout>`,
+meaning a single git repository regroups several different Composer packages,
+built from several git repositories split from this repository.
+Contributions need to be made against that mono repository.
+
+To clone the repository, run the following command::
+
+    git clone [email protected]:phpDocumentor/guides.git
+
 Run the tests
 =============
 

docs/contributions/monorepository-layout.rst

@@ -0,0 +1,27 @@
+..  include:: /include.rst.txt
+
+===============
+Mono repository
+===============
+
+This project uses a mono repository approach. This means that all the
+development happens in a single repository, later split into multiple
+repositories for distribution.
+
+Consequences:
+
+- The mono repository is not installable as a Composer package, and its
+  ``composer.json`` file is not even valid because there is no package
+  name. Its purpose is to help installing development dependencies, and
+  dependencies of each component.
+- The ``require`` section of the root ``composer.json`` file should only
+  contain the list of the components.
+- The ``autoload-dev`` section of the root ``composer.json`` file should
+  make all the components's test support code available.
+- The ``require-dev`` section of the root ``composer.json`` file of
+  components should only be used to mention optional dependencies, and
+  not actual development dependencies.
+- Issues and pull requests should be opened in the mono repository, and
+  not in the component repositories.
+
+The components are located under the ``packages`` directory.

packages/guides-graphs/src/Graphs/Renderer/PlantumlRenderer.php

@@ -14,6 +14,7 @@
 namespace phpDocumentor\Guides\Graphs\Renderer;
 
 use Psr\Log\LoggerInterface;
+use Symfony\Component\Process\Exception\RuntimeException;
 use Symfony\Component\Process\Process;
 
 use function file_get_contents;
@@ -44,12 +45,17 @@ public function render(string $diagram): string|null
 
         $pumlFileLocation = tempnam(sys_get_temp_dir() . '/phpdocumentor', 'pu_');
         file_put_contents($pumlFileLocation, $output);
+        try {
+            $process = new Process([$this->plantUmlBinaryPath, '-tsvg', $pumlFileLocation], __DIR__, null, null, 600.0);
+            $process->run();
 
-        $process = new Process([$this->plantUmlBinaryPath, '-tsvg', $pumlFileLocation], __DIR__, null, null, 600.0);
-        $process->run();
+            if (!$process->isSuccessful()) {
+                $this->logger->error('Generating the class diagram failed', ['error' => $process->getErrorOutput()]);
 
-        if (!$process->isSuccessful()) {
-            $this->logger->error('Generating the class diagram failed', ['error' => $process->getErrorOutput()]);
+                return null;
+            }
+        } catch (RuntimeException $e) {
+            $this->logger->error('Generating the class diagram failed', ['error' => $e->getMessage()]);
 
             return null;
         }

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

@@ -56,6 +56,8 @@
 use phpDocumentor\Guides\RestructuredText\MarkupLanguageParser;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContextFactory;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineParser;
+use phpDocumentor\Guides\RestructuredText\Parser\Interlink\DefaultInterlinkParser;
+use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\AnnotationRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\BlockQuoteRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\CommentRule;
@@ -232,6 +234,8 @@
         ->set('phpdoc.guides.parser.rst.body_elements', RuleContainer::class)
         ->set('phpdoc.guides.parser.rst.structural_elements', RuleContainer::class)
 
+        ->set(InterlinkParser::class, DefaultInterlinkParser::class)
+
         ->set(AnnotationRule::class)
         ->tag('phpdoc.guides.parser.rst.body_element', ['priority' => AnnotationRule::PRIORITY])
         ->set(LinkRule::class)

packages/guides-restructured-text/src/RestructuredText/Parser/Interlink/DefaultInterlinkParser.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Parser\Interlink;
+
+use function preg_match;
+
+final class DefaultInterlinkParser implements InterlinkParser
+{
+    /** @see https://regex101.com/r/htMn5p/1 */
+    private const INTERLINK_REGEX = '/^([a-zA-Z0-9-_]+):(.*$)/';
+
+    public function extractInterlink(string $fullReference): InterlinkData
+    {
+        if (!preg_match(self::INTERLINK_REGEX, $fullReference, $matches)) {
+            return new InterlinkData($fullReference, '');
+        }
+
+        return new InterlinkData($matches[2], $matches[1] ?? '');
+    }
+}

packages/guides-restructured-text/src/RestructuredText/Parser/Interlink/InterlinkData.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Parser\Interlink;
+
+class InterlinkData
+{
+    public function __construct(
+        public readonly string $reference,
+        public readonly string $interlink,
+    ) {
+    }
+}

packages/guides-restructured-text/src/RestructuredText/Parser/Interlink/InterlinkParser.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Parser\Interlink;
+
+interface InterlinkParser
+{
+    public function extractInterlink(string $fullReference): InterlinkData;
+}

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

@@ -13,9 +13,6 @@ abstract class AbstractReferenceTextRole implements TextRole
 {
     use EmbeddedUriParser;
 
-    /** @see https://regex101.com/r/htMn5p/1 */
-    public const INTERLINK_REGEX = '/^([a-zA-Z0-9-_]+):(.*$)/';
-
     public function processNode(
         DocumentParserContext $documentParserContext,
         string $role,

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

@@ -6,13 +6,17 @@
 
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
-
-use function preg_match;
+use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
 
 class DocReferenceTextRole extends AbstractReferenceTextRole
 {
     final public const NAME = 'doc';
 
+    public function __construct(
+        private readonly InterlinkParser $interlinkParser,
+    ) {
+    }
+
     public function getName(): string
     {
         return self::NAME;
@@ -27,15 +31,8 @@ public function getAliases(): array
     /** @return DocReferenceNode */
     protected function createNode(string $referenceTarget, string|null $referenceName, string $role): AbstractLinkInlineNode
     {
-        $pattern =  AbstractReferenceTextRole::INTERLINK_REGEX;
-        if (preg_match($pattern, $referenceTarget, $matches)) {
-            $interlinkDomain = $matches[1];
-            $path = $matches[2];
-        } else {
-            $interlinkDomain = '';
-            $path = $referenceTarget;
-        }
-
-        return new DocReferenceNode($path, $referenceName ?? '', $interlinkDomain);
+        $interlinkData = $this->interlinkParser->extractInterlink($referenceTarget);
+
+        return new DocReferenceNode($interlinkData->reference, $referenceName ?? '', $interlinkData->interlink);
     }
 }

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

@@ -7,15 +7,16 @@
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorReducer;
+use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
 
 use function array_keys;
-use function preg_match;
 
 class GenericReferenceTextRole extends AbstractReferenceTextRole
 {
     public function __construct(
         private readonly GenericLinkProvider $genericLinkProvider,
         private readonly AnchorReducer $anchorReducer,
+        private readonly InterlinkParser $interlinkParser,
     ) {
     }
 
@@ -34,15 +35,9 @@ public function getAliases(): array
     protected function createNode(string $referenceTarget, string|null $referenceName, string $role): AbstractLinkInlineNode
     {
         $linkType = $this->genericLinkProvider->getLinkType($role);
-        $pattern = '/^([a-zA-Z0-9]+):(.*$)/';
-        if (preg_match(AbstractReferenceTextRole::INTERLINK_REGEX, $referenceTarget, $matches)) {
-            $interlinkDomain = $matches[1];
-            $id = $this->anchorReducer->reduceAnchor($matches[2]);
-        } else {
-            $interlinkDomain = '';
-            $id = $this->anchorReducer->reduceAnchor($referenceTarget);
-        }
-
-        return new ReferenceNode($id, $referenceName ?? '', $interlinkDomain, $linkType);
+        $interlinkData = $this->interlinkParser->extractInterlink($referenceTarget);
+        $reference = $this->anchorReducer->reduceAnchor($interlinkData->reference);
+
+        return new ReferenceNode($reference, $referenceName ?? '', $interlinkData->interlink, $linkType);
     }
 }