Merge pull request #534 from phpDocumentor/feature-highlight-directive

[FEATURE] introduce highlight directive

Author: jaapio

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

@@ -18,6 +18,7 @@
 use phpDocumentor\Guides\RestructuredText\Directives\DocumentBlockDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\ErrorDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\FigureDirective;
+use phpDocumentor\Guides\RestructuredText\Directives\HighlightDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\HintDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\ImageDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\ImportantDirective;
@@ -158,6 +159,7 @@
         ->set(DocumentBlockDirective::class)
         ->set(ErrorDirective::class)
         ->set(FigureDirective::class)
+        ->set(HighlightDirective::class)
         ->set(HintDirective::class)
         ->set(ImageDirective::class)
         ->set(ImportantDirective::class)

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

@@ -50,7 +50,12 @@ public function process(
             $blockContext->getDocumentIterator()->toArray(),
         );
 
-        $node->setLanguage(trim($directive->getData()));
+        if (trim($directive->getData()) !== '') {
+            $node->setLanguage(trim($directive->getData()));
+        } else {
+            $node->setLanguage($blockContext->getDocumentParserContext()->getCodeBlockDefaultLanguage());
+        }
+
         $this->setStartingLineNumberBasedOnOptions($directive->getOptions(), $node);
         $this->setCaptionBasedOnOptions($directive->getOptions(), $node);
         $this->codeNodeOptionMapper->apply($node, $directive->getOptions());

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

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Directives;
+
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+
+use function trim;
+
+/**
+ * https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-highlight
+ */
+class HighlightDirective extends ActionDirective
+{
+    public function getName(): string
+    {
+        return 'highlight';
+    }
+
+    public function processAction(
+        BlockContext $blockContext,
+        Directive $directive,
+    ): void {
+        $blockContext->getDocumentParserContext()->setCodeBlockDefaultLanguage(trim($directive->getData()));
+    }
+}

packages/guides-restructured-text/src/RestructuredText/Parser/DocumentParserContext.php

@@ -34,6 +34,8 @@ class DocumentParserContext
     /* Each Document has its own text role factory as text roles can be changed on a per document base
         by directives */
     private TextRoleFactory $textRoleFactoryForDocument;
+    
+    private string $codeBlockDefaultLanguage = '';
 
     /** @var string[] */
     private array $titleLetters = [];
@@ -95,4 +97,14 @@ public function getTextRoleFactoryForDocument(): TextRoleFactory
     {
         return $this->textRoleFactoryForDocument;
     }
+    
+    public function getCodeBlockDefaultLanguage(): string
+    {
+        return $this->codeBlockDefaultLanguage;
+    }
+
+    public function setCodeBlockDefaultLanguage(string $codeBlockDefaultLanguage): void
+    {
+        $this->codeBlockDefaultLanguage = $codeBlockDefaultLanguage;
+    }
 }

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

@@ -63,7 +63,7 @@ public function apply(BlockContext $blockContext, CompoundNode|null $on = null):
         }
 
         //TODO this is a bug, we need LiteralBlockNode here
-        return new CodeNode($lines);
+        return new CodeNode($lines, $blockContext->getDocumentParserContext()->getCodeBlockDefaultLanguage());
     }
 
     private function isBlockLine(string|null $line): bool

packages/guides/src/Nodes/CodeNode.php

@@ -17,15 +17,13 @@
 
 class CodeNode extends TextNode
 {
-    protected string|null $language = null;
-
     /** @var int|null The line number to start counting from and display, or null to hide line numbers */
     private int|null $startingLineNumber = null;
 
     private string|null $caption = null;
 
     /** @param string[] $lines */
-    public function __construct(array $lines)
+    public function __construct(array $lines, protected string|null $language = null)
     {
         parent::__construct(implode("\n", $lines));
     }

tests/Integration/tests/code-block-hightlight/expected/index.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>Title</title>
+
+</head>
+<body>
+    <div class="section" id="title">
+    <h1>Title</h1>
+
+            <p>The default language is empty:</p>
+            <pre><code class="language-">    Some plain text
+</code></pre>
+            <p>Also in explicit code-blocks without language:</p>
+            <pre><code class="language-">Some plain text</code></pre>
+            <p>Now the default language is JavaScript:</p>
+            <pre><code class="language-javascript">    var language = &#039;JavaScript&#039;;
+</code></pre>
+            <p>Also in explicit code-blocks without language:</p>
+            <pre><code class="language-javascript">var language = &#039;JavaScript&#039;;</code></pre>
+            <p>However explicit languages take precedence</p>
+            <pre><code class="language-xml">&lt;language&gt;XML&lt;/language&gt;</code></pre>
+    </div>
+
+</body>
+</html>

tests/Integration/tests/code-block-hightlight/input/index.rst

@@ -0,0 +1,30 @@
+Title
+=====
+
+The default language is empty::
+
+    Some plain text
+
+Also in explicit code-blocks without language:
+
+..  code-block::
+
+    Some plain text
+
+..  highlight:: javascript
+
+Now the default language is JavaScript::
+
+    var language = 'JavaScript';
+
+Also in explicit code-blocks without language:
+
+..  code-block::
+
+    var language = 'JavaScript';
+
+However explicit languages take precedence
+
+..  code-block:: xml
+
+    <language>XML</language>