[FEATURE] Add Meta-information markup

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#meta-information-markup

resolves #847

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

@@ -43,6 +43,7 @@
 use phpDocumentor\Guides\RestructuredText\Directives\RawDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\ReplaceDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\RoleDirective;
+use phpDocumentor\Guides\RestructuredText\Directives\SectionauthorDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\SeeAlsoDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\SidebarDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\SubDirective;
@@ -216,6 +217,7 @@
         ->set(RawDirective::class)
         ->set(ReplaceDirective::class)
         ->set(RoleDirective::class)
+        ->set(SectionauthorDirective::class)
         ->set(SeeAlsoDirective::class)
         ->set(SidebarDirective::class)
         ->set(TableDirective::class)

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

@@ -0,0 +1,81 @@
+<?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\AuthorNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use Psr\Log\LoggerInterface;
+
+use function preg_match;
+
+final class SectionauthorDirective extends BaseDirective
+{
+    public const NAME_EMAIL_REGEX = '/^(?P<name>[\w\s]+)(?: <(?P<email>[^>]+)>)?$/';
+
+    public function __construct(
+        private readonly LoggerInterface $logger,
+    ) {
+    }
+
+    public function getName(): string
+    {
+        return 'sectionauthor';
+    }
+
+    /**
+     * When the default domain contains a class directive, this directive will be shadowed. Therefore, Sphinx re-exports it as rst-class.
+     *
+     * See https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rstclass
+     *
+     * @return string[]
+     */
+    public function getAliases(): array
+    {
+        return ['codeauthor'];
+    }
+
+    /** {@inheritDoc}
+     *
+     * @param Directive $directive
+     */
+    public function process(
+        BlockContext $blockContext,
+        Directive $directive,
+    ): Node|null {
+        $input = $directive->getData();
+        $directiveName = $directive->getName();
+        if ($input === '') {
+            $this->logger->warning('`.. ' . $directiveName . ' ::` directive could not be parsed: `' . $input . '`', $blockContext->getLoggerInformation());
+
+            return null;
+        }
+
+        if (!preg_match(self::NAME_EMAIL_REGEX, $input, $matches)) {
+            $this->logger->warning('Content of `.. ' . $directiveName . ':: name <email>` must specify a name and can also specify an email', $blockContext->getLoggerInformation());
+
+            return null;
+        }
+
+        $name = $matches['name'];
+        $email = $matches['email'] ?? null;
+        $context = match ($directiveName) {
+            'sectionauthor' => AuthorNode::CONTEXT_SECTION,
+            default => AuthorNode::CONTEXT_CODE,
+        };
+
+        return new AuthorNode($name, [], $context, $email);
+    }
+}

packages/guides/resources/template/html/body/author.html.twig

@@ -0,0 +1,4 @@
+<address itemprop="author" itemscope itemtype="http://schema.org/Person">
+    <p>Author: <span itemprop="name">{node.value}</span></p>
+    <p>Email: <a href="mailto:{node.email}"><span itemprop="email">{node.email}</span></a></p>
+</address>

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

@@ -57,6 +57,7 @@
 
 return [
     AnchorNode::class => 'inline/anchor.html.twig',
+    \phpDocumentor\Guides\Nodes\AuthorNode::class => 'body/author.html.twig',
     FigureNode::class => 'body/figure.html.twig',
     MetaNode::class => 'structure/header/meta.html.twig',
     ParagraphNode::class => 'body/paragraph.html.twig',

packages/guides/src/Nodes/AuthorNode.php

@@ -0,0 +1,61 @@
+<?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;
+
+use function filter_var;
+
+use const FILTER_VALIDATE_EMAIL;
+
+/**
+ * The author element holds the name of the author of a document, section or code-block
+ *
+ * @extends AbstractNode<string>
+ */
+final class AuthorNode extends AbstractNode
+{
+    public const CONTEXT_DOCUMENT = 'document';
+    public const CONTEXT_SECTION = 'section';
+    public const CONTEXT_CODE = 'code';
+
+    /** @param Node[] $children */
+    public function __construct(
+        string $value,
+        private readonly array $children,
+        private readonly string $context = self::CONTEXT_DOCUMENT,
+        private string|null $email = null,
+    ) {
+        $this->value = $value;
+        if (filter_var($email ?? '', FILTER_VALIDATE_EMAIL)) {
+            return;
+        }
+
+        $this->email = null;
+    }
+
+    /** @return Node[] */
+    public function getChildren(): array
+    {
+        return $this->children;
+    }
+
+    public function getEmail(): string|null
+    {
+        return $this->email;
+    }
+
+    public function getContext(): string
+    {
+        return $this->context;
+    }
+}

tests/Integration/tests/body-elements/line-blocks/expected/index.html

@@ -1,38 +1,41 @@
 <!-- content start -->
     <div class="section" id="line-blocks">
-    <h1>Line Blocks</h1>
+            <h1>Line Blocks</h1>
 
-        <div class="line-block">
-            <div class="line">
-                Line blocks are useful for addresses,
-            </div>
-            <div class="line">
-                verse, and adornment-free lists.
-            </div>
-            <div class="line">
-                <br>
-            </div>
-            <div class="line">
-                Each new line begins with a
-            </div>
-            <div class="line">
-                vertical bar (&quot;|&quot;).
-            </div>
             <div class="line-block">
-                <div class="line">
-                    Line breaks and initial indents
-                </div>
-                <div class="line">
-                    are preserved.
-                </div>
-            </div>
-            <div class="line">
-                Continuation lines are wrapped
-                portions of long lines; they begin
-                with spaces in place of vertical bars.
-            </div>
-        </div>
-        <p>This is normal text</p>
+    <div class="line">
+    Line blocks are useful for addresses,
+</div>
+<div class="line">
+    verse, and adornment-free lists.
+</div>
+<div class="line">
+    <br>
+</div>
+<div class="line">
+    Each new line begins with a
+</div>
+<div class="line">
+    vertical bar (&quot;|&quot;).
+</div>
+<div class="line-block">
+    <div class="line">
+    Line breaks and initial indents
+</div>
+<div class="line">
+    are preserved.
+</div>
+
+</div>
+<div class="line">
+    Continuation lines are wrapped
+  portions of long lines; they begin
+  with spaces in place of vertical bars.
+</div>
+
+</div>
+
+            <p>This is normal text</p>
     </div>
 
 <!-- content end -->

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

@@ -0,0 +1,33 @@
+<!-- content start -->
+    <div class="section" id="document-title">
+            <h1>Document Title</h1>
+
+            <div class="section" id="some-section">
+            <h2>Some Section</h2>
+
+            <address itemprop="author" itemscope itemtype="http://schema.org/Person">
+    <p>Author: <span itemprop="name">{node.value}</span></p>
+    <p>Email: <a href="mailto:{node.email}"><span itemprop="email">{node.email}</span></a></p>
+</address>
+
+    </div>
+
+            <div class="section" id="some-other-section">
+            <h2>Some other section</h2>
+
+            <address itemprop="author" itemscope itemtype="http://schema.org/Person">
+    <p>Author: <span itemprop="name">{node.value}</span></p>
+    <p>Email: <a href="mailto:{node.email}"><span itemprop="email">{node.email}</span></a></p>
+</address>
+
+            <address itemprop="author" itemscope itemtype="http://schema.org/Person">
+    <p>Author: <span itemprop="name">{node.value}</span></p>
+    <p>Email: <a href="mailto:{node.email}"><span itemprop="email">{node.email}</span></a></p>
+</address>
+
+            <pre><code class="language-rst">Lorem *Ipsum* Dolor</code></pre>
+    </div>
+
+    </div>
+
+<!-- content end -->

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

@@ -0,0 +1,19 @@
+==============
+Document Title
+==============
+
+Some Section
+============
+
+..  sectionauthor:: Lina Wolf <lina.wolf@typo3.org>
+
+Some other section
+==================
+
+..  sectionauthor:: Lina Wolf
+
+..  codeauthor:: Lina Wolf <lina.wolf@typo3.org>
+
+..  code-block:: rst
+
+    Lorem *Ipsum* Dolor

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

@@ -1,9 +1,10 @@
 <!-- content start -->
-<div class="section" id="document-title">
-    <h1>Document Title</h1>
+    <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>
+            <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>
 
-</div>
 <!-- content end -->

tests/Integration/tests/images/figure-relative/expected/index.html

@@ -49,6 +49,7 @@ <h2>An image with relative paths</h2>
 </figcaption>
             </figure>
 
+
     </div>
 
     </div>

tests/Integration/tests/images/figure-relative/expected/subfolder/subpage.html

@@ -33,6 +33,7 @@ <h2>An image with relative paths</h2>
 </figcaption>
             </figure>
 
+
     </div>
 
     </div>

tests/Integration/tests/images/image-absolute/expected/index.html

@@ -28,6 +28,7 @@ <h2>An image with relative paths</h2>
     src="/images/hero2-illustration.svg"
     width="400"            alt="Alternative text"        />
 
+
     </div>
 
     </div>

tests/Integration/tests/images/image-relative/expected/index.html

@@ -28,6 +28,7 @@ <h2>An image with relative paths</h2>
     src="images/hero2-illustration.svg"
     width="400"            alt="Alternative text"        />
 
+
     </div>
 
     </div>

tests/Integration/tests/images/image-relative/expected/subfolder/subpage.html

@@ -19,6 +19,7 @@ <h2>An image with relative paths</h2>
     src="../images/hero2-illustration.svg"
     width="400"            alt="Alternative text"        />
 
+
     </div>
 
     </div>