[FEATURE] Add line block support

Line blocks are just lines in a div that can be nested using indentation.
Every line must start with an | and a block ends when an empty line is detected.

I implemented this using ContainerNodes because it's an rst only type, and it
has no other behavior rather than just some custom styling.

Author: jaapio

resources/config/guides-restructured-text.php

@@ -89,6 +89,7 @@
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\GridTableRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineMarkupRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules\InlineRule;
+use phpDocumentor\Guides\RestructuredText\Parser\Productions\LineBlockRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\LinkRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\ListRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\LiteralBlockRule;
@@ -256,6 +257,8 @@
         ->set(EnumeratedListRule::class)
         ->arg('$productions', service('phpdoc.guides.parser.rst.body_elements'))
         ->tag('phpdoc.guides.parser.rst.body_element', ['priority' => EnumeratedListRule::PRIORITY])
+        ->set(LineBlockRule::class)
+        ->tag('phpdoc.guides.parser.rst.body_element', ['priority' => ParagraphRule::PRIORITY + 1])
         ->set(DirectiveRule::class)
         ->arg('$directives', tagged_iterator('phpdoc.guides.directive'))
         ->tag('phpdoc.guides.parser.rst.body_element', ['priority' => DirectiveRule::PRIORITY])

src/RestructuredText/NodeRenderers/Html/ContainerNodeRenderer.php

@@ -21,6 +21,7 @@
 use phpDocumentor\Guides\TemplateRenderer;
 
 use function is_a;
+use function trim;
 
 /** @implements NodeRenderer<ContainerNode> */
 final class ContainerNodeRenderer implements NodeRenderer
@@ -44,7 +45,7 @@ public function render(Node $node, RenderContext $renderContext): string
             $renderContext,
             'body/container.html.twig',
             [
-                'class' => $node->getOption('class'),
+                'class' => trim($node->getOption('class') . ' ' . $node->getClassesString()),
                 'id' => $node->getOption('name'),
                 'node' => $node->getValue(),
             ],

src/RestructuredText/Parser/Productions/LineBlockRule.php

@@ -0,0 +1,117 @@
+<?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\Parser\Productions;
+
+use phpDocumentor\Guides\Nodes\CompoundNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\NewlineInlineNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Nodes\ContainerNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Buffer;
+use phpDocumentor\Guides\RestructuredText\Parser\LinesIterator;
+use phpDocumentor\Guides\RestructuredText\Parser\UnindentStrategy;
+
+use function ltrim;
+use function mb_strlen;
+use function str_starts_with;
+use function substr;
+
+/** @implements Rule<ContainerNode> */
+final class LineBlockRule implements Rule
+{
+    public function __construct(
+        private InlineMarkupRule $inlineMarkupRule,
+    ) {
+    }
+
+    public function applies(BlockContext $blockContext): bool
+    {
+        return str_starts_with($blockContext->getDocumentIterator()->current(), '| ')
+            && $blockContext->getDocumentIterator()->getNextLine() !== null
+            && str_starts_with($blockContext->getDocumentIterator()->getNextLine(), '| ');
+    }
+
+    public function apply(BlockContext $blockContext, CompoundNode|null $on = null): Node|null
+    {
+        return $this->createLineBlock($blockContext);
+    }
+
+    private function collectContentLines(BlockContext $blockContext): Buffer
+    {
+        $buffer = new Buffer(
+            [
+                substr($blockContext->getDocumentIterator()->current(), 2),
+            ],
+            UnindentStrategy::NONE,
+        );
+
+        $blockContext->getDocumentIterator()->next();
+
+        while (
+            $blockContext->getDocumentIterator()->valid()
+            && LinesIterator::isEmptyLine($blockContext->getDocumentIterator()->current()) === false
+            && str_starts_with($blockContext->getDocumentIterator()->current(), '|') === false
+        ) {
+            $buffer->push($blockContext->getDocumentIterator()->current());
+            $blockContext->getDocumentIterator()->next();
+        }
+
+        return $buffer;
+    }
+
+    /** @return CompoundNode<InlineNode> */
+    private function createLine(BlockContext $blockContext, Buffer $buffer): CompoundNode
+    {
+        $line = $this->inlineMarkupRule->apply(new BlockContext(
+            $blockContext->getDocumentParserContext(),
+            $buffer->getLinesString(),
+            true,
+        ));
+
+        if ($line->getChildren() === []) {
+            $line->addChildNode(new NewlineInlineNode());
+        }
+
+        return $line;
+    }
+
+    private function createLineBlock(BlockContext $blockContext, int $indent = 0): ContainerNode
+    {
+        $lineBlock = new ContainerNode();
+        $lineBlock->setClasses(['line-block']);
+
+        while (
+            $blockContext->getDocumentIterator()->valid()
+            && LinesIterator::isEmptyLine($blockContext->getDocumentIterator()->current()) === false
+            && ($indent === 0 || LinesIterator::isIndented(substr($blockContext->getDocumentIterator()->current(), 2), $indent))
+        ) {
+            if (LinesIterator::isIndented(substr($blockContext->getDocumentIterator()->current(), 2), $indent + 1)) {
+                $line = substr($blockContext->getDocumentIterator()->current(), 2);
+                $lineBlock->addChildNode(
+                    $this->createLineBlock($blockContext, mb_strlen($line) - mb_strlen(ltrim($line))),
+                );
+                continue;
+            }
+
+            $child = new ContainerNode();
+            $child->setClasses(['line']);
+            $buffer = $this->collectContentLines($blockContext);
+            $child->addChildNode($this->createLine($blockContext, $buffer));
+            $lineBlock->addChildNode($child);
+        }
+
+        return $lineBlock;
+    }
+}