[FEATURE] Support math directive

resolves: #928
releases: main, 1.0

Author: linawolf

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

@@ -34,6 +34,7 @@
 use phpDocumentor\Guides\RestructuredText\Directives\LaTeXMain;
 use phpDocumentor\Guides\RestructuredText\Directives\ListTableDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\LiteralincludeDirective;
+use phpDocumentor\Guides\RestructuredText\Directives\MathDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\MenuDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\MetaDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\NoteDirective;
@@ -213,6 +214,7 @@
                 CodeNodeOptionMapper::class,
             ),
         ])
+        ->set(MathDirective::class)
         ->set(MetaDirective::class)
         ->set(NoteDirective::class)
         ->set(OptionDirective::class)

packages/guides-restructured-text/src/RestructuredText/Directives/MathDirective.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\MathNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Renders a code block, example:
+ *
+ * .. code-block:: php
+ *
+ *      <?php
+ *
+ *      echo "Hello world!\n";
+ *
+ * @link https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block
+ */
+final class MathDirective extends BaseDirective
+{
+    public function __construct(
+        private readonly LoggerInterface $logger,
+    ) {
+    }
+
+    public function getName(): string
+    {
+        return 'math';
+    }
+
+    /** {@inheritDoc} */
+    public function getAliases(): array
+    {
+        return [];
+    }
+
+    /** {@inheritDoc} */
+    public function process(
+        BlockContext $blockContext,
+        Directive $directive,
+    ): Node|null {
+        if ($blockContext->getDocumentIterator()->isEmpty()) {
+            $this->logger->warning('The math directive has no content. Did you properly indent the code? ', $blockContext->getLoggerInformation());
+
+            return null;
+        }
+
+        return new MathNode(
+            $blockContext->getDocumentIterator()->toArray(),
+        );
+    }
+}

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

@@ -0,0 +1 @@
+<math{%- if node.class %} class="{{ node.class }}"{% endif %}>{{ node.value|raw }}</math>

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

@@ -34,6 +34,7 @@
 use phpDocumentor\Guides\Nodes\ListItemNode;
 use phpDocumentor\Guides\Nodes\ListNode;
 use phpDocumentor\Guides\Nodes\LiteralBlockNode;
+use phpDocumentor\Guides\Nodes\MathNode;
 use phpDocumentor\Guides\Nodes\Metadata\AddressNode;
 use phpDocumentor\Guides\Nodes\Metadata\AuthorNode;
 use phpDocumentor\Guides\Nodes\Metadata\AuthorsNode;
@@ -75,6 +76,7 @@
     ListNode::class => 'body/list/list.html.twig',
     ListItemNode::class => 'body/list/list-item.html.twig',
     LiteralBlockNode::class => 'body/literal-block.html.twig',
+    MathNode::class => 'body/math.html.twig',
     CitationNode::class => 'body/citation.html.twig',
     FootnoteNode::class => 'body/footnote.html.twig',
     AnnotationListNode::class => 'body/annotation-list.html.twig',

packages/guides/src/Nodes/MathNode.php

@@ -0,0 +1,25 @@
+<?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 implode;
+
+final class MathNode extends TextNode
+{
+    /** @param string[] $lines */
+    public function __construct(array $lines)
+    {
+        parent::__construct(implode("\n", $lines));
+    }
+}

tests/Integration/tests/directives/directive-math/expected/index.html

@@ -0,0 +1,29 @@
+<!-- content start -->
+    <div class="section" id="directive-tests">
+            <h1>Directive tests</h1>
+
+            <math><mrow>
+    <mi>α</mi>
+    <mi>t</mi>
+    <mo stretchy="false">(</mo>
+    <mi>i</mi>
+    <mo stretchy="false">)</mo>
+    <mo>=</mo>
+    <mi>P</mi>
+    <mo stretchy="false">(</mo>
+    <mi>O</mi>
+    <msub>
+        <mi>t</mi>
+        <mo>,</mo>
+        <mi>i</mi>
+    </msub>
+    <mo>=</mo>
+    <mi>S</mi>
+    <mi>i</mi>
+    <mi>λ</mi>
+    <mo stretchy="false">)</mo>
+</mrow></math>
+
+    </div>
+
+<!-- content end -->

tests/Integration/tests/directives/directive-math/input/index.rst

@@ -0,0 +1,26 @@
+Directive tests
+===============
+
+..  math::
+
+    <mrow>
+        <mi>α</mi>
+        <mi>t</mi>
+        <mo stretchy="false">(</mo>
+        <mi>i</mi>
+        <mo stretchy="false">)</mo>
+        <mo>=</mo>
+        <mi>P</mi>
+        <mo stretchy="false">(</mo>
+        <mi>O</mi>
+        <msub>
+            <mi>t</mi>
+            <mo>,</mo>
+            <mi>i</mi>
+        </msub>
+        <mo>=</mo>
+        <mi>S</mi>
+        <mi>i</mi>
+        <mi>λ</mi>
+        <mo stretchy="false">)</mo>
+    </mrow>