Merge pull request #867 from phpDocumentor/task/ignore-domain

[TASK] Ignore domains with unknows directives and textroles
phpDocumentor · Mar 1, 2024 · f235c57 · f235c57
2 parents 4d9f353 + c784542
commit f235c57
Show file tree

Hide file tree

Showing 12 changed files with 140 additions and 14 deletions.
diff --git a/guides.xml b/guides.xml
@@ -11,6 +11,8 @@
         log-path="php://stder"
 >
     <project title="Guides"/>
+    <ignored_domain>phpdoc</ignored_domain>
+    <ignored_domain>php</ignored_domain>
     <extension class="phpDocumentor\Guides\Bootstrap"/>
     <extension class="phpDocumentor\Guides\Code"/>
 </guides>
diff --git a/packages/guides-cli/resources/schema/guides.xsd b/packages/guides-cli/resources/schema/guides.xsd
@@ -14,6 +14,7 @@
             <xsd:element name="base-template-path" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
             <xsd:element name="extension" type="extension" minOccurs="0" maxOccurs="unbounded"/>
             <xsd:element name="output-format" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
+            <xsd:element name="ignored_domain" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
             <xsd:element name="inventory" type="inventory" minOccurs="0" maxOccurs="unbounded"/>
             <xsd:element name="template" type="template" minOccurs="0" maxOccurs="unbounded"/>
         </xsd:choice>

diff --git a/packages/guides-restructured-text/resources/config/guides-restructured-text.php b/packages/guides-restructured-text/resources/config/guides-restructured-text.php
@@ -116,6 +116,7 @@
 use phpDocumentor\Guides\RestructuredText\TextRoles\TextRoleFactory;
 use phpDocumentor\Guides\RestructuredText\Toc\GlobSearcher;
 use phpDocumentor\Guides\RestructuredText\Toc\ToctreeBuilder;
+use phpDocumentor\Guides\Settings\SettingsManager;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
 
@@ -234,9 +235,11 @@
         ->set(WarningDirective::class)
         ->set(YoutubeDirective::class)
 
-
+        ->set(GenericTextRole::class, GenericTextRole::class)
+        ->arg('$settingsManager', inline_service(SettingsManager::class))
         ->set(DefaultTextRoleFactory::class, DefaultTextRoleFactory::class)
-        ->arg('$genericTextRole', inline_service(GenericTextRole::class))
+        ->arg('$genericTextRole', service(GenericTextRole::class))
+
         ->arg('$defaultTextRole', inline_service(LiteralTextRole::class))
         ->arg('$textRoles', tagged_iterator('phpdoc.guides.parser.rst.text_role'))
         ->alias(TextRoleFactory::class, DefaultTextRoleFactory::class)

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/GeneralDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/GeneralDirective.php
@@ -19,12 +19,26 @@
 use phpDocumentor\Guides\RestructuredText\Nodes\GeneralDirectiveNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
+use phpDocumentor\Guides\Settings\SettingsManager;
+
+use function explode;
+use function in_array;
+use function str_contains;
 
 /**
  * A catch-all directive, the content is treated as content, the options passed on
  */
 final class GeneralDirective extends SubDirective
 {
+    /** @param Rule<CollectionNode> $startingRule */
+    public function __construct(
+        Rule $startingRule,
+        private readonly SettingsManager $settingsManager,
+    ) {
+        parent::__construct($startingRule);
+    }
+
     public function getName(): string
     {
         return '';
@@ -39,6 +53,13 @@ protected function processSub(
         CollectionNode $collectionNode,
         Directive $directive,
     ): Node|null {
+        if (str_contains($directive->getName(), ':')) {
+            [$domainName, $directiveName] = explode(':', $directive->getName());
+            if (in_array($domainName, $this->settingsManager->getProjectSettings()->getIgnoredDomains(), true)) {
+                return $collectionNode;
+            }
+        }
+
         return new GeneralDirectiveNode(
             $directive->getName(),
             $directive->getData(),

diff --git a/packages/guides-restructured-text/src/RestructuredText/TextRoles/GenericTextRole.php b/packages/guides-restructured-text/src/RestructuredText/TextRoles/GenericTextRole.php
@@ -14,19 +14,38 @@
 namespace phpDocumentor\Guides\RestructuredText\TextRoles;
 
 use phpDocumentor\Guides\Nodes\Inline\GenericTextRoleInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+use phpDocumentor\Guides\Settings\SettingsManager;
+
+use function explode;
+use function in_array;
+use function str_contains;
 
 final class GenericTextRole extends BaseTextRole
 {
     protected string $name = 'default';
     protected string|null $baseRole = null;
 
+    public function __construct(
+        private readonly SettingsManager $settingsManager,
+    ) {
+    }
+
     public function processNode(
         DocumentParserContext $documentParserContext,
         string $role,
         string $content,
         string $rawContent,
-    ): GenericTextRoleInlineNode {
+    ): InlineNode {
+        if (str_contains($role, ':')) {
+            [$domainName, $directiveName] = explode(':', $role);
+            if (in_array($domainName, $this->settingsManager->getProjectSettings()->getIgnoredDomains(), true)) {
+                return new PlainTextInlineNode($content);
+            }
+        }
+
         return new GenericTextRoleInlineNode($this->baseRole ?? $role, $content, $this->getClass());
     }
 

diff --git a/...ides-restructured-text/tests/unit/NodeRenderers/Html/GeneralDirectiveNodeRendererTest.php b/...ides-restructured-text/tests/unit/NodeRenderers/Html/GeneralDirectiveNodeRendererTest.php
@@ -20,6 +20,7 @@
 use phpDocumentor\Guides\RestructuredText\TextRoles\DefaultTextRoleFactory;
 use phpDocumentor\Guides\RestructuredText\TextRoles\GenericTextRole;
 use phpDocumentor\Guides\RestructuredText\TextRoles\LiteralTextRole;
+use phpDocumentor\Guides\Settings\SettingsManager;
 use phpDocumentor\Guides\TemplateRenderer;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\MockObject\MockObject;
@@ -40,7 +41,7 @@ public function setUp(): void
             new Logger('test'),
         );
         $textRoleFactory = new DefaultTextRoleFactory(
-            new GenericTextRole(),
+            new GenericTextRole(self::createMock(SettingsManager::class)),
             new LiteralTextRole(),
             [],
         );

diff --git a/packages/guides-restructured-text/tests/unit/Parser/InlineTokenParserTest.php b/packages/guides-restructured-text/tests/unit/Parser/InlineTokenParserTest.php
@@ -47,6 +47,7 @@
 use phpDocumentor\Guides\RestructuredText\TextRoles\GenericTextRole;
 use phpDocumentor\Guides\RestructuredText\TextRoles\LiteralTextRole;
 use phpDocumentor\Guides\RestructuredText\TextRoles\ReferenceTextRole;
+use phpDocumentor\Guides\Settings\SettingsManager;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 
@@ -59,7 +60,7 @@ final class InlineTokenParserTest extends TestCase
     public function setUp(): void
     {
         $this->textRoleFactory = new DefaultTextRoleFactory(
-            new GenericTextRole(),
+            new GenericTextRole(self::createMock(SettingsManager::class)),
             new LiteralTextRole(),
             [
                 new ReferenceTextRole(),

diff --git a/packages/guides-restructured-text/tests/unit/Parser/Productions/DirectiveRuleTest.php b/packages/guides-restructured-text/tests/unit/Parser/Productions/DirectiveRuleTest.php
@@ -21,6 +21,7 @@
 use phpDocumentor\Guides\RestructuredText\Directives\OptionMapper\CodeNodeOptionMapper;
 use phpDocumentor\Guides\RestructuredText\Parser\DummyBaseDirective;
 use phpDocumentor\Guides\RestructuredText\Parser\DummyNode;
+use phpDocumentor\Guides\Settings\SettingsManager;
 use PHPUnit\Framework\Attributes\DataProvider;
 
 use function array_values;
@@ -36,7 +37,7 @@ public function setUp(): void
         $this->rule = new DirectiveRule(
             $this->givenInlineMarkupRule(),
             new Logger('test'),
-            new GeneralDirective(new DirectiveContentRule(new RuleContainer())),
+            new GeneralDirective(new DirectiveContentRule(new RuleContainer()), self::createMock(SettingsManager::class)),
             [$this->directiveHandler],
         );
     }
@@ -112,7 +113,7 @@ public function testCodeBlockValue(string $input, string $expectedValue): void
         $this->rule = new DirectiveRule(
             $this->givenInlineMarkupRule(),
             new Logger('test'),
-            new GeneralDirective(new DirectiveContentRule(new RuleContainer())),
+            new GeneralDirective(new DirectiveContentRule(new RuleContainer()), self::createMock(SettingsManager::class)),
             [$this->directiveHandler, new CodeBlockDirective($logger, $this->createMock(CodeNodeOptionMapper::class))],
         );
         $context = $this->createContext($input);

diff --git a/packages/guides-restructured-text/tests/unit/TextRoles/DefaultTextRoleFactoryTest.php b/packages/guides-restructured-text/tests/unit/TextRoles/DefaultTextRoleFactoryTest.php
@@ -14,6 +14,7 @@
 namespace phpDocumentor\Guides\RestructuredText\TextRoles;
 
 use Monolog\Logger;
+use phpDocumentor\Guides\Settings\SettingsManager;
 use PHPUnit\Framework\TestCase;
 
 final class DefaultTextRoleFactoryTest extends TestCase
@@ -25,7 +26,7 @@ public function setUp(): void
     {
         $this->logger = new Logger('test');
         $this->defaultTextRoleFactory = new DefaultTextRoleFactory(
-            new GenericTextRole(),
+            new GenericTextRole(self::createMock(SettingsManager::class)),
             new LiteralTextRole(),
             [],
             [],
@@ -38,12 +39,6 @@ public function testUnknownTextRoleReturnsGenericTextRole(): void
         self::assertInstanceOf(GenericTextRole::class, $textRole);
     }
 
-    public function testUnknownDomainReturnsGenericTextRole(): void
-    {
-        $textRole = $this->defaultTextRoleFactory->getTextRole('unknown', 'unknown');
-        self::assertInstanceOf(GenericTextRole::class, $textRole);
-    }
-
     public function testRegisteredTextRoleIsReturned(): void
     {
         $this->defaultTextRoleFactory->registerTextRole(new AbbreviationTextRole($this->logger));

diff --git a/packages/guides-restructured-text/tests/unit/TextRoles/GenericTextRoleTest.php b/packages/guides-restructured-text/tests/unit/TextRoles/GenericTextRoleTest.php
@@ -0,0 +1,53 @@
+<?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\GenericTextRoleInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+use phpDocumentor\Guides\Settings\ProjectSettings;
+use phpDocumentor\Guides\Settings\SettingsManager;
+use PHPUnit\Framework\TestCase;
+
+final class GenericTextRoleTest extends TestCase
+{
+    private SettingsManager $settingsManager;
+    private ProjectSettings $projectSettings;
+    private GenericTextRole $subject;
+    private DocumentParserContext $documentParserContext;
+
+    public function setUp(): void
+    {
+        $this->projectSettings = new ProjectSettings();
+        $this->settingsManager = new SettingsManager($this->projectSettings);
+        $this->documentParserContext = self::createMock(DocumentParserContext::class);
+        $this->subject = new GenericTextRole(
+            $this->settingsManager,
+        );
+    }
+
+    public function testIgnoredDomainReturnsPlainTextInlineNode(): void
+    {
+        $this->projectSettings->setIgnoredDomains(['ignored', 'alsoignored']);
+        $inline = $this->subject->processNode($this->documentParserContext, 'ignored:role', '', '');
+        self::assertInstanceOf(PlainTextInlineNode::class, $inline);
+    }
+
+    public function testUnknownDomainReturnsGenericTextRoleInlineNode(): void
+    {
+        $this->projectSettings->setIgnoredDomains(['ignored', 'alsoignored']);
+        $inline = $this->subject->processNode($this->documentParserContext, 'notignored:role', '', '');
+        self::assertInstanceOf(GenericTextRoleInlineNode::class, $inline);
+    }
+}
diff --git a/packages/guides/src/DependencyInjection/GuidesExtension.php b/packages/guides/src/DependencyInjection/GuidesExtension.php
@@ -104,6 +104,16 @@ static function ($value) {
                     ->end()
                     ->scalarPrototype()->end()
                 ->end()
+                ->arrayNode('ignored_domain')
+                    ->defaultValue([])
+                    ->beforeNormalization()
+                    ->ifString()
+                    ->then(static function ($value) {
+                        return [$value];
+                    })
+                    ->end()
+                    ->scalarPrototype()->end()
+                ->end()
                 ->scalarNode('log_path')->end()
                 ->scalarNode('fail_on_log')->end()
                 ->scalarNode('fail_on_error')->end()
@@ -217,6 +227,10 @@ public function load(array $configs, ContainerBuilder $container): void
             $projectSettings->setOutputFormats($config['output_format']);
         }
 
+        if (isset($config['ignored_domain']) && is_array($config['ignored_domain'])) {
+            $projectSettings->setIgnoredDomains($config['ignored_domain']);
+        }
+
         if (isset($config['links_are_relative'])) {
             $projectSettings->setLinksRelative((bool) $config['links_are_relative']);
         }

diff --git a/packages/guides/src/Settings/ProjectSettings.php b/packages/guides/src/Settings/ProjectSettings.php
@@ -35,6 +35,9 @@ final class ProjectSettings
     private string $defaultCodeLanguage = '';
     private int $maxMenuDepth = 0;
 
+    /** @var string[] */
+    private array $ignoredDomains = [];
+
     public function getTitle(): string
     {
         return $this->title;
@@ -215,4 +218,16 @@ public function setMaxMenuDepth(int $maxMenuDepth): ProjectSettings
 
         return $this;
     }
+
+    /** @return string[] */
+    public function getIgnoredDomains(): array
+    {
+        return $this->ignoredDomains;
+    }
+
+    /** @param string[] $ignoredDomains */
+    public function setIgnoredDomains(array $ignoredDomains): void
+    {
+        $this->ignoredDomains = $ignoredDomains;
+    }
 }