feature #141 Support captions (file paths) for code blocks (javiereguiluz)

This PR was merged into the main branch.

Discussion
----------

Support captions (file paths) for code blocks

Commits
-------

b9eec4a Support captions (file paths) for code blocks

Author: javiereguiluz

src/Directive/CodeBlockDirective.php

@@ -37,6 +37,8 @@ public function process(Parser $parser, ?Node $node, string $variable, string $d
         // CodeNodeRenderer can then use it when rendering
         $node->setClasses(isset($options['class']) ? explode(' ', $options['class']) : []);
 
+        $node->setOptions(array_merge($node->getOptions(), ['caption' => $options['caption'] ?? null]));
+
         if ('' !== $variable) {
             $environment = $parser->getEnvironment();
             $environment->setVariable($variable, $node);

src/Renderers/CodeNodeRenderer.php

@@ -81,6 +81,13 @@ public function render(): string
         $numOfLines = \count(preg_split('/\r\n|\r|\n/', $highlightedCode));
         $lineNumbers = implode("\n", range(1, $numOfLines));
 
+        // 'caption' is used by code blocks to define the path of the file they belong to
+        // 'patch_file' is a special value used by "diff patches", which don't correspond to any file
+        $codeCaption = $this->codeNode->getOptions()['caption'] ?? null;
+        if ('patch_file' === $codeCaption) {
+            $codeCaption = null;
+        }
+
         return $this->templateRenderer->render(
             'code.html.twig',
             [
@@ -92,6 +99,7 @@ public function render(): string
                 // the length of the codeblock in a semantic way (to tweak styling)
                 // e.g. LOC = 5, length = 'sm'; LOC = 18, length = 'md'
                 'length' => [1 => 'sm', 2 => 'md', 3 => 'lg', 4 => 'xl'][strlen((string) $numOfLines)],
+                'caption' => $codeCaption,
             ]
         );
     }

src/Templates/default/html/code.html.twig

@@ -1,4 +1,7 @@
 <div translate="no" data-loc="{{ loc }}" class="notranslate codeblock codeblock-length-{{ length }} {{ languages|map(language => "codeblock-#{language}")|join(' ') }}{% if custom_css_classes %} {{ custom_css_classes }}{% endif %}">
+    {% if caption %}
+        <div class="codeblock-caption">{{ caption }}</div>
+    {% endif %}
     <div class="codeblock-scroll">
         <pre class="codeblock-lines">{{ line_numbers }}</pre>
         <pre class="codeblock-code"><code>{{ code|raw }}</code></pre>

tests/IntegrationTest.php

@@ -232,6 +232,10 @@ public function parserUnitBlockProvider()
             'blockName' => 'references/reference-and-code',
         ];
 
+        yield 'code-block-caption' => [
+            'blockName' => 'code-blocks/code-caption',
+        ];
+
         yield 'code-block-php' => [
             'blockName' => 'code-blocks/php',
         ];

tests/fixtures/expected/blocks/code-blocks/code-caption.html

@@ -0,0 +1,44 @@
+<div translate="no" data-loc="1" class="notranslate codeblock codeblock-length-sm codeblock-php">
+   <div class="codeblock-caption">config/routes.php</div>
+   <div class="codeblock-scroll">
+       <pre class="codeblock-lines">1</pre>
+       <pre class="codeblock-code">
+       <code>
+           <span class="hljs-variable">
+               <span class="hljs-variable-other-marker">$</span>
+               foo</span>
+           =
+           <span class="hljs-string">'bar'</span>;</code>
+   </pre>
+   </div>
+</div>
+
+<div translate="no" data-loc="1" class="notranslate codeblock codeblock-length-sm codeblock-php hide">
+   <div class="codeblock-caption">config/routes.php</div>
+   <div class="codeblock-scroll">
+       <pre class="codeblock-lines">1</pre>
+       <pre class="codeblock-code">
+       <code>
+           <span class="hljs-variable">
+               <span class="hljs-variable-other-marker">$</span>
+               foo</span>
+           =
+           <span class="hljs-string">'bar'</span>;</code>
+   </pre>
+   </div>
+</div>
+
+<div translate="no" data-loc="3" class="notranslate codeblock codeblock-length-sm codeblock-diff">
+       <div class="codeblock-scroll">
+           <pre class="codeblock-lines">1
+2
+3</pre>
+       <pre class="codeblock-code">
+       <code>
+           <span class="hljs-comment">--- a/src/Controller/DefaultController.php</span>
+           <span class="hljs-comment">+++ b/src/Controller/DefaultController.php</span>
+           <span class="hljs-meta">@@ -2,7 +2,9 @@</span>
+       </code>
+   </pre>
+   </div>
+</div>

tests/fixtures/source/blocks/code-blocks/code-caption.rst

@@ -0,0 +1,20 @@
+
+.. code-block:: php
+    :caption: config/routes.php
+
+    $foo = 'bar';
+
+
+.. code-block:: php
+    :caption: config/routes.php
+    :class: hide
+
+    $foo = 'bar';
+
+.. code-block:: diff
+    :caption: patch_file
+    :emphasize-lines: 1,2
+
+    --- a/src/Controller/DefaultController.php
+    +++ b/src/Controller/DefaultController.php
+    @@ -2,7 +2,9 @@