Skip to content

Commit c22ec47

Browse files
jaapiojaapio
committed
Markdown supports more nesting on nodes than RST does.
To support this we needed to add support for compound nodes. We tried to be backward compatible for people building their own template. This layer will be removed in v2 and therfor we do trigger deprecations. See #1161 Fixes: #1160
1 parent e68d1c4 commit c22ec47

34 files changed

+266
-67
lines changed

‎packages/guides-markdown/src/Markdown/Parsers/InlineParsers/AbstractInlineParser.php

+3-3
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@
1717
use League\CommonMark\Node\NodeWalker;
1818
use phpDocumentor\Guides\Markdown\ParserInterface;
1919
use phpDocumentor\Guides\MarkupLanguageParser;
20-
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
20+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
2121

2222
/**
23-
* @template TValue as InlineNode
23+
* @template TValue as InlineNodeInterface
2424
* @implements ParserInterface<TValue>
2525
*/
2626
abstract class AbstractInlineParser implements ParserInterface
2727
{
28-
abstract public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNode;
28+
abstract public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNodeInterface;
2929
}

‎packages/guides-markdown/src/Markdown/Parsers/InlineParsers/AbstractInlineTextDecoratorParser.php

+6-8
Original file line numberDiff line numberDiff line change
@@ -18,16 +18,16 @@
1818
use League\CommonMark\Node\NodeWalkerEvent;
1919
use phpDocumentor\Guides\MarkupLanguageParser;
2020
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
21+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
2122
use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
2223
use Psr\Log\LoggerInterface;
2324
use RuntimeException;
2425

2526
use function count;
2627
use function sprintf;
27-
use function var_export;
2828

2929
/**
30-
* @template TValue as InlineNode
30+
* @template TValue as InlineNodeInterface
3131
* @extends AbstractInlineParser<TValue>
3232
*/
3333
abstract class AbstractInlineTextDecoratorParser extends AbstractInlineParser
@@ -40,7 +40,7 @@ public function __construct(
4040
}
4141

4242
/** @return TValue */
43-
public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNode
43+
public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNodeInterface
4444
{
4545
$content = [];
4646

@@ -66,12 +66,10 @@ public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMa
6666

6767
if ($this->supportsCommonMarkNode($commonMarkNode)) {
6868
if (count($content) === 1 && $content[0] instanceof PlainTextInlineNode) {
69-
return $this->createInlineNode($commonMarkNode, $content[0]->getValue());
69+
return $this->createInlineNode($commonMarkNode, $content[0]->getValue(), $content);
7070
}
7171

72-
$this->logger->warning(sprintf('%s CONTEXT: Content of emphasis could not be interpreted: %s', $this->getType(), var_export($content, true)));
73-
74-
return $this->createInlineNode($commonMarkNode, null);
72+
return $this->createInlineNode($commonMarkNode, null, $content);
7573
}
7674

7775
$this->logger->warning(sprintf('%s context does not allow a %s node', $this->getType(), $commonMarkNode::class));
@@ -83,7 +81,7 @@ public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMa
8381
abstract protected function getType(): string;
8482

8583
/** @return TValue */
86-
abstract protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNode;
84+
abstract protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNodeInterface;
8785

8886
abstract protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool;
8987

‎packages/guides-markdown/src/Markdown/Parsers/InlineParsers/EmphasisParser.php

+4-2
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
use League\CommonMark\Node\Node as CommonMarkNode;
1818
use phpDocumentor\Guides\Nodes\Inline\EmphasisInlineNode;
1919
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
20+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
2021
use Psr\Log\LoggerInterface;
2122

2223
/** @extends AbstractInlineTextDecoratorParser<EmphasisInlineNode> */
@@ -35,9 +36,10 @@ protected function getType(): string
3536
return 'Emphasis';
3637
}
3738

38-
protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNode
39+
/** @param InlineNodeInterface[] $children */
40+
protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content, array $children = []): InlineNodeInterface
3941
{
40-
return new EmphasisInlineNode($content ?? '');
42+
return new EmphasisInlineNode($content ?? '', $children);
4143
}
4244

4345
protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

‎packages/guides-markdown/src/Markdown/Parsers/InlineParsers/InlineCodeParser.php

+2-1
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,15 @@
1818
use League\CommonMark\Node\NodeWalker;
1919
use League\CommonMark\Node\NodeWalkerEvent;
2020
use phpDocumentor\Guides\MarkupLanguageParser;
21+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
2122
use phpDocumentor\Guides\Nodes\Inline\LiteralInlineNode;
2223

2324
use function assert;
2425

2526
/** @extends AbstractInlineParser<LiteralInlineNode> */
2627
final class InlineCodeParser extends AbstractInlineParser
2728
{
28-
public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): LiteralInlineNode
29+
public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNodeInterface
2930
{
3031
assert($current instanceof Code);
3132

‎packages/guides-markdown/src/Markdown/Parsers/InlineParsers/InlineImageParser.php

+2-1
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
use League\CommonMark\Node\Node as CommonMarkNode;
1818
use phpDocumentor\Guides\Nodes\Inline\ImageInlineNode;
1919
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
20+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
2021
use Psr\Log\LoggerInterface;
2122

2223
use function assert;
@@ -38,7 +39,7 @@ protected function getType(): string
3839
return 'Image';
3940
}
4041

41-
protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNode
42+
protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNodeInterface
4243
{
4344
assert($commonMarkNode instanceof Image);
4445

‎packages/guides-markdown/src/Markdown/Parsers/InlineParsers/LinkParser.php

+4-2
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
use League\CommonMark\Node\Node as CommonMarkNode;
1818
use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
1919
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
20+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
2021
use Psr\Log\LoggerInterface;
2122

2223
use function assert;
@@ -42,7 +43,8 @@ protected function getType(): string
4243
return 'Link';
4344
}
4445

45-
protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNode
46+
/** @param InlineNodeInterface[] $children */
47+
protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content, array $children = []): InlineNodeInterface
4648
{
4749
assert($commonMarkNode instanceof Link);
4850

@@ -52,7 +54,7 @@ protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null
5254
$url = substr($url, 0, -3);
5355
}
5456

55-
return new HyperLinkNode($content, $url);
57+
return new HyperLinkNode($content, $url, $children);
5658
}
5759

5860
protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

‎packages/guides-markdown/src/Markdown/Parsers/InlineParsers/NewLineParser.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
use League\CommonMark\Node\NodeWalker;
1919
use League\CommonMark\Node\NodeWalkerEvent;
2020
use phpDocumentor\Guides\MarkupLanguageParser;
21-
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
21+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
2222
use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
2323

2424
/** @extends AbstractInlineParser<PlainTextInlineNode> */
@@ -28,7 +28,7 @@ public function __construct()
2828
{
2929
}
3030

31-
public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNode
31+
public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNodeInterface
3232
{
3333
return new PlainTextInlineNode(' ');
3434
}

‎packages/guides-markdown/src/Markdown/Parsers/InlineParsers/StrongParser.php

+4-2
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
use League\CommonMark\Extension\CommonMark\Node\Inline\Strong;
1717
use League\CommonMark\Node\Node as CommonMarkNode;
1818
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
19+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
1920
use phpDocumentor\Guides\Nodes\Inline\StrongInlineNode;
2021
use Psr\Log\LoggerInterface;
2122

@@ -35,9 +36,10 @@ protected function getType(): string
3536
return 'StrongDecorator';
3637
}
3738

38-
protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNode
39+
/** @param InlineNodeInterface[] $children */
40+
protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content, array $children = []): InlineNodeInterface
3941
{
40-
return new StrongInlineNode($content ?? '');
42+
return new StrongInlineNode($content ?? '', $children);
4143
}
4244

4345
protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

‎packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/DefaultTextRoleRule.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
1515

16-
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
16+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
1717
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
1818
use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
1919

@@ -27,7 +27,7 @@ public function applies(InlineLexer $lexer): bool
2727
return $lexer->token?->type === InlineLexer::BACKTICK;
2828
}
2929

30-
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
30+
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
3131
{
3232
$text = '';
3333

‎packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/EmphasisRule.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
1515

1616
use phpDocumentor\Guides\Nodes\Inline\EmphasisInlineNode;
17-
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
17+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
1818
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
1919
use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
2020

@@ -28,7 +28,7 @@ public function applies(InlineLexer $lexer): bool
2828
return $lexer->token?->type === InlineLexer::EMPHASIS_DELIMITER;
2929
}
3030

31-
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
31+
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
3232
{
3333
$text = '';
3434

‎packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/InlineRule.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,15 @@
1313

1414
namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
1515

16-
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
16+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
1717
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
1818
use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
1919

2020
interface InlineRule
2121
{
2222
public function applies(InlineLexer $lexer): bool;
2323

24-
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null;
24+
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null;
2525

2626
public function getPriority(): int;
2727
}

‎packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/InternalReferenceRule.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
1515

16-
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
16+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
1717
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
1818
use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
1919

@@ -24,7 +24,7 @@ public function applies(InlineLexer $lexer): bool
2424
return $lexer->token?->type === InlineLexer::UNDERSCORE;
2525
}
2626

27-
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
27+
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
2828
{
2929
$text = '';
3030
$initialPosition = $lexer->token?->position;

‎packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/NamedPhraseRule.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
1515

16-
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
16+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
1717
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
1818
use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
1919
use phpDocumentor\Guides\RestructuredText\Parser\References\EmbeddedReferenceParser;
@@ -37,7 +37,7 @@ public function applies(InlineLexer $lexer): bool
3737
return $lexer->token?->type === InlineLexer::BACKTICK;
3838
}
3939

40-
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
40+
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
4141
{
4242
$value = '';
4343
$initialPosition = $lexer->token?->position;

‎packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/NamedReferenceRule.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
1515

16-
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
16+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
1717
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
1818
use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
1919

@@ -35,7 +35,7 @@ public function applies(InlineLexer $lexer): bool
3535
return $lexer->token?->type === InlineLexer::NAMED_REFERENCE;
3636
}
3737

38-
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
38+
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
3939
{
4040
$value = rtrim($lexer->token?->value ?? '', '_');
4141
$node = $this->createReference($blockContext, $value);

‎packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/StrongRule.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
1515

16-
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
16+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
1717
use phpDocumentor\Guides\Nodes\Inline\StrongInlineNode;
1818
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
1919
use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
@@ -28,7 +28,7 @@ public function applies(InlineLexer $lexer): bool
2828
return $lexer->token?->type === InlineLexer::STRONG_DELIMITER;
2929
}
3030

31-
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
31+
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
3232
{
3333
$text = '';
3434

‎packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/TextRoleRule.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
1515

16-
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
16+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
1717
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
1818
use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
1919

@@ -29,7 +29,7 @@ public function applies(InlineLexer $lexer): bool
2929
return $lexer->token?->type === InlineLexer::COLON;
3030
}
3131

32-
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
32+
public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
3333
{
3434
$domain = null;
3535
$role = null;

‎packages/guides-restructured-text/src/RestructuredText/Parser/Productions/LineBlockRule.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
namespace phpDocumentor\Guides\RestructuredText\Parser\Productions;
1515

1616
use phpDocumentor\Guides\Nodes\CompoundNode;
17-
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
17+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
1818
use phpDocumentor\Guides\Nodes\Inline\NewlineInlineNode;
1919
use phpDocumentor\Guides\Nodes\Node;
2020
use phpDocumentor\Guides\RestructuredText\Nodes\ContainerNode;
@@ -71,7 +71,7 @@ private function collectContentLines(BlockContext $blockContext): Buffer
7171
return $buffer;
7272
}
7373

74-
/** @return CompoundNode<InlineNode> */
74+
/** @return CompoundNode<InlineNodeInterface> */
7575
private function createLine(BlockContext $blockContext, Buffer $buffer): CompoundNode
7676
{
7777
$line = $this->inlineMarkupRule->apply(new BlockContext(

‎packages/guides-restructured-text/src/RestructuredText/TextRoles/TextRole.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\RestructuredText\TextRoles;
1515

16-
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
16+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
1717
use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
1818

1919
interface TextRole
@@ -32,5 +32,5 @@ public function processNode(
3232
string $role,
3333
string $content,
3434
string $rawContent,
35-
): InlineNode;
35+
): InlineNodeInterface;
3636
}

‎packages/guides-theme-rst/resources/template/rst/template.php

+1-1
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,6 @@
7676
AnnotationListNode::class => 'body/annotation-list.rst.twig',
7777
// Inline
7878
ImageInlineNode::class => 'inline/image.rst.twig',
79-
InlineCompoundNode::class => 'inline/inline-node.rst.twig',
8079
AbbreviationInlineNode::class => 'inline/textroles/abbreviation.rst.twig',
8180
CitationInlineNode::class => 'inline/citation.rst.twig',
8281
DocReferenceNode::class => 'inline/doc.rst.twig',
@@ -91,6 +90,7 @@
9190
StrongInlineNode::class => 'inline/strong.rst.twig',
9291
VariableInlineNode::class => 'inline/variable.rst.twig',
9392
GenericTextRoleInlineNode::class => 'inline/textroles/generic.rst.twig',
93+
InlineCompoundNode::class => 'inline/inline-node.rst.twig',
9494
// Output as Metatags
9595
AuthorNode::class => 'structure/header/author.rst.twig',
9696
CopyrightNode::class => 'structure/header/copyright.rst.twig',

‎packages/guides/resources/template/html/inline/emphasis.html.twig

+5-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,5 @@
1-
<em>{{- node.value -}}</em>
1+
<em>
2+
{%- for child in node.children -%}
3+
{{- renderNode(child) -}}
4+
{%- endfor -%}
5+
</em>

0 commit comments

Comments
 (0)