[FEATURE] add youtube directive

This new directive allows users to embed youtube video's in their docs.

Author: jaapio

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

@@ -55,6 +55,7 @@
 use phpDocumentor\Guides\RestructuredText\Directives\VersionAddedDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\VersionChangedDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\WarningDirective;
+use phpDocumentor\Guides\RestructuredText\Directives\YoutubeDirective;
 use phpDocumentor\Guides\RestructuredText\MarkupLanguageParser;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContextFactory;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineParser;
@@ -229,6 +230,7 @@
         ->set(VersionAddedDirective::class)
         ->set(VersionChangedDirective::class)
         ->set(WarningDirective::class)
+        ->set(YoutubeDirective::class)
 
 
         ->set(DefaultTextRoleFactory::class, DefaultTextRoleFactory::class)

packages/guides-restructured-text/src/RestructuredText/Directives/YoutubeDirective.php

@@ -0,0 +1,66 @@
+<?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\Directives;
+
+use phpDocumentor\Guides\Nodes\EmbeddedFrame;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+
+use function array_filter;
+
+/**
+ * This directive is used to embed a youtube video in the document.
+ *
+ * Basic usage
+ *
+ * ```rst
+ *   .. youtube:: dQw4w9WgXcQ
+ * ```
+ *
+ * Options:
+ *
+ * - string title The title of the video
+ * - int width The width of the video, default is 560
+ * - int height The height of the video, default is 315
+ * - string allow The allow attribute of the iframe, default is 'encrypted-media; picture-in-picture; web-share'
+ * - bool allowfullscreen Whether the video should be allowed to go fullscreen, default is true
+ */
+final class YoutubeDirective extends BaseDirective
+{
+    public function getName(): string
+    {
+        return 'youtube';
+    }
+
+    public function process(
+        BlockContext $blockContext,
+        Directive $directive,
+    ): EmbeddedFrame {
+        $node = new EmbeddedFrame(
+            'https://www.youtube-nocookie.com/embed/' . $directive->getData(),
+        );
+
+        return $node->withOptions(
+            array_filter(
+                [
+                    'width' => $directive->getOption('width')->getValue() ?? 560,
+                    'title' => $directive->getOption('title')->getValue(),
+                    'height' => $directive->getOption('height')->getValue() ?? 315,
+                    'allow' => $directive->getOption('allow')->getValue() ?? 'encrypted-media; picture-in-picture; web-share',
+                    'allowfullscreen' => (bool) ($directive->getOption('allowfullscreen')->getValue() ?? true),
+                ],
+            ),
+        );
+    }
+}

packages/guides/resources/template/html/body/embedded-frame.html.twig

@@ -0,0 +1,8 @@
+<iframe src="{{ node.url }}"
+        {%- if node.hasOption('width') %} width="{{ node.option('width') }}"{% endif -%}
+        {%- if node.hasOption('height') %} height="{{ node.option('height') }}"{% endif -%}
+        {%- if node.hasOption('title') %} title="{{ node.option('title') }}"{% endif -%}
+        {%- if node.hasOption('allow') %} allow="{{ node.option('allow') }}"{% endif -%}
+        {%- if node.hasOption('allowfullscreen') and node.option('allowfullscreen') %} allowfullscreen{% endif -%}
+        >
+</iframe>

packages/guides/resources/template/html/template.php

@@ -10,6 +10,7 @@
 use phpDocumentor\Guides\Nodes\DefinitionListNode;
 use phpDocumentor\Guides\Nodes\DefinitionLists\DefinitionNode;
 use phpDocumentor\Guides\Nodes\DocumentNode;
+use phpDocumentor\Guides\Nodes\EmbeddedFrame;
 use phpDocumentor\Guides\Nodes\FieldListNode;
 use phpDocumentor\Guides\Nodes\FigureNode;
 use phpDocumentor\Guides\Nodes\FootnoteNode;
@@ -76,6 +77,7 @@
     CitationNode::class => 'body/citation.html.twig',
     FootnoteNode::class => 'body/footnote.html.twig',
     AnnotationListNode::class => 'body/annotation-list.html.twig',
+    EmbeddedFrame::class => 'body/embedded-frame.html.twig',
     // Inline
     ImageInlineNode::class => 'inline/image.html.twig',
     InlineCompoundNode::class => 'inline/inline-node.html.twig',

packages/guides/src/Nodes/EmbeddedFrame.php

@@ -0,0 +1,28 @@
+<?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\Nodes;
+
+final class EmbeddedFrame extends TextNode
+{
+    public function __construct(
+        private readonly string $url,
+    ) {
+        parent::__construct($url);
+    }
+
+    public function getUrl(): string
+    {
+        return $this->url;
+    }
+}

tests/Integration/tests/directives/youtube/expected/index.html

@@ -1,5 +1,9 @@
 <!-- content start -->
-    .. youtube:: dtRKsxzjKj0
+<div class="section" id="document-title">
+    <h1>Document Title</h1>
 
+    <iframe src="https://www.youtube-nocookie.com/embed/hdDD0SNJ-pk" width="560" height="315" title="PHP DocBlock - Adding Comments to Classes &amp; Methods" allow="encrypted-media; picture-in-picture; web-share" allowfullscreen>
+    </iframe>
 
+</div>
 <!-- content end -->

tests/Integration/tests/directives/youtube/input/index.rst

@@ -1,2 +1,6 @@
+==============
+Document Title
+==============
 
-..  youtube:: dtRKsxzjKj0
+..  youtube:: hdDD0SNJ-pk
+    :title: PHP DocBlock - Adding Comments to Classes & Methods