feature #120 Add support for an alternative screencast directive (javiereguiluz, weaverryan)

This PR was merged into the main branch.

Discussion
----------

Add support for an alternative screencast directive

In #119 we added the `.. screencast::` directive, but Symfony Docs still use the old `.. admonition:: Screencast` syntax.

We cannot update Symfony Docs yet, so we need to support both. I thought that the simple code of this PR would be enough, but it's not working. Anyone knows why? Thanks!

Commits
-------

add05d8 Fixing test to not rely on screencast style admonition
18dd3dc Fixing initialization or Parser in test
f080e8b Add support for an alternative screencast directive

Author: weaverryan

src/DocsKernel.php

@@ -15,7 +15,9 @@
 use Doctrine\RST\ErrorManager;
 use Doctrine\RST\Event\PostBuildRenderEvent;
 use Doctrine\RST\Event\PreNodeRenderEvent;
+use Doctrine\RST\Event\PreParseDocumentEvent;
 use Doctrine\RST\Kernel;
+use SymfonyDocsBuilder\Listener\AdmonitionListener;
 use SymfonyDocsBuilder\Listener\AssetsCopyListener;
 use SymfonyDocsBuilder\Listener\CopyImagesListener;
 
@@ -42,6 +44,11 @@ public function initBuilder(Builder $builder): void
 
     private function initializeListeners(EventManager $eventManager, ErrorManager $errorManager)
     {
+        $eventManager->addEventListener(
+           PreParseDocumentEvent::PRE_PARSE_DOCUMENT,
+           new AdmonitionListener()
+       );
+
         $eventManager->addEventListener(
            PreNodeRenderEvent::PRE_NODE_RENDER,
            new CopyImagesListener($this->buildConfig, $errorManager)

src/Listener/AdmonitionListener.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Listener;
+
+use Doctrine\RST\Event\PreParseDocumentEvent;
+
+final class AdmonitionListener
+{
+    public function preParseDocument(PreParseDocumentEvent $event)
+    {
+        // TODO: remove this temporary fix when Symfony Docs are updated to use the new '.. screencast::' directive
+        $event->setContents(str_replace('.. admonition:: Screencast', '.. screencast::', $event->getContents()));
+    }
+}

tests/IntegrationTest.php

@@ -9,6 +9,7 @@
 
 namespace SymfonyDocsBuilder\Tests;
 
+use Doctrine\RST\Builder;
 use Doctrine\RST\Configuration;
 use Doctrine\RST\Parser;
 use Gajus\Dindent\Indenter;
@@ -90,9 +91,10 @@ public function testParseUnitBlock(string $blockName)
         $configuration = new Configuration();
         $configuration->setCustomTemplateDirs([__DIR__.'/Templates']);
 
-        $parser = new Parser(
-            KernelFactory::createKernel($this->createBuildConfig(sprintf('%s/fixtures/source/blocks', __DIR__)))
-        );
+        $kernel = KernelFactory::createKernel($this->createBuildConfig(sprintf('%s/fixtures/source/blocks', __DIR__)));
+        // necessary because this initializes some listeners on the kernel
+        $builder = new Builder($kernel);
+        $parser = new Parser($kernel);
 
         $sourceFile = sprintf('%s/fixtures/source/blocks/%s.rst', __DIR__, $blockName);
 

tests/fixtures/expected/blocks/directives/admonition.html

@@ -1,5 +1,5 @@
-<div class="admonition admonition-default screencast_class">
+<div class="admonition admonition-default some_admonition_class">
     <p class="admonition-title">
-        <span>Screencast</span>
-    </p><p>Do you prefer video tutorials? Check out the the screencasts.</p>
+        <span>Some Admonition</span>
+    </p><p>Do you prefer admonitions? Well then... enjoy this one!</p>
 </div>

tests/fixtures/expected/blocks/directives/screencast.html

@@ -9,3 +9,15 @@
 <a href="https://symfonycasts.com/screencast/symfony" class="reference external" rel="external noopener noreferrer" target="_blank">Stellar Development with Symfony</a>
 screencast series.</p>
 </div>
+
+<div class="admonition admonition-screencast ">
+    <p class="admonition-title">
+        <svg xmlns="http://www.w3.org/2000/svg" fill="none" width="24" height="24" viewbox="0 0 24 24" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 10l4.553-2.276A1 1 0 0121 8.618v6.764a1 1 0 01-1.447.894L15 14M5 18h8a2 2 0 002-2V8a2 2 0 00-2-2H5a2 2 0 00-2 2v8a2 2 0 002 2z"></path>
+        </svg>
+        <span>Screencast</span>
+    </p>
+    <p>Do you prefer video tutorials? Check out the
+<a href="https://symfonycasts.com/screencast/symfony" class="reference external" rel="external noopener noreferrer" target="_blank">Stellar Development with Symfony</a>
+screencast series.</p>
+</div>

tests/fixtures/source/blocks/directives/admonition.rst

@@ -1,4 +1,4 @@
-.. admonition:: Screencast
-    :class: screencast_class
+.. admonition:: Some Admonition
+    :class: some_admonition_class
 
-    Do you prefer video tutorials? Check out the the screencasts.
+    Do you prefer admonitions? Well then... enjoy this one!

tests/fixtures/source/blocks/directives/screencast.rst

@@ -3,3 +3,9 @@
     Do you prefer video tutorials? Check out the
     `Stellar Development with Symfony <https://symfonycasts.com/screencast/symfony>`_
     screencast series.
+
+.. admonition:: Screencast
+
+    Do you prefer video tutorials? Check out the
+    `Stellar Development with Symfony <https://symfonycasts.com/screencast/symfony>`_
+    screencast series.